@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,18 @@
|
|
|
1
|
+
/** What a gate may resolve with: `{ once: true }` satisfies it for the rest of the client's life. */
|
|
2
|
+
export type CreateGroupGateResult = void | {
|
|
3
|
+
readonly once?: boolean;
|
|
4
|
+
};
|
|
5
|
+
/** A `beforeCreateGroup` gate: `groups.create()` waits until it resolves and aborts with its rejection. */
|
|
6
|
+
export type CreateGroupGate = () => Promise<CreateGroupGateResult> | CreateGroupGateResult;
|
|
7
|
+
export interface BeforeCreateGroupGates {
|
|
8
|
+
/** Registers `gate`; returns its unregister function (idempotent). */
|
|
9
|
+
register(gate: CreateGroupGate): () => void;
|
|
10
|
+
/** Resolves once every registered, not yet satisfied gate resolved (serialised); rejects with the first rejection. */
|
|
11
|
+
pass(): Promise<void>;
|
|
12
|
+
}
|
|
13
|
+
export interface BeforeCreateGroupDeps {
|
|
14
|
+
/** Invokes a gate through the client's re-entrancy guard. */
|
|
15
|
+
call(gate: CreateGroupGate): Promise<CreateGroupGateResult>;
|
|
16
|
+
isDisposed(): boolean;
|
|
17
|
+
}
|
|
18
|
+
export declare function createBeforeCreateGroupGates(deps: BeforeCreateGroupDeps): BeforeCreateGroupGates;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `extensions.beforeCreateGroup(gate)` (S7, AC-INBOX-7): gates consulted by
|
|
3
|
+
* `groups.create()` before it does anything else — no signer call, no
|
|
4
|
+
* KeyPackage, no store write happens until every registered gate resolved.
|
|
5
|
+
*
|
|
6
|
+
* - A gate that rejects aborts that `create()` with the gate's own rejection
|
|
7
|
+
* (the same error value); nothing is created.
|
|
8
|
+
* - A gate that resolves with `{ once: true }` is satisfied for the rest of
|
|
9
|
+
* this client instance: it is never invoked again (a reload — a new
|
|
10
|
+
* client — asks it again). Any other resolution lets this one creation
|
|
11
|
+
* through and the next `create()` invokes it again.
|
|
12
|
+
* - Gate passes are serialised per client: concurrent `create()` calls wait
|
|
13
|
+
* for the gate invocation in flight instead of invoking it alongside it, so
|
|
14
|
+
* a `once: true` gate is invoked at most once even under concurrency, and a
|
|
15
|
+
* non-once gate once per creation. Several gates run in registration order.
|
|
16
|
+
* - Each invocation is a consumer surface (ADR-013, `beforeCreateGroup`):
|
|
17
|
+
* `groups.create()` from inside a gate is rejected `reentrant` — it would
|
|
18
|
+
* wait on the very gate pass that awaits it. Without an async-context
|
|
19
|
+
* carrier (browsers) only a synchronous re-entry is detectable; an
|
|
20
|
+
* awaited asynchronous one deadlocks this client's `groups.create()`
|
|
21
|
+
* (the residue ADR-013 Decision item 4 states).
|
|
22
|
+
*
|
|
23
|
+
* Per-instance state only (one registry per client, INV-NO-SINGLETONS).
|
|
24
|
+
*/
|
|
25
|
+
import { MarmotError } from '../shared/index.js';
|
|
26
|
+
function reportsOnce(result) {
|
|
27
|
+
return typeof result === 'object' && result !== null && result.once === true;
|
|
28
|
+
}
|
|
29
|
+
export function createBeforeCreateGroupGates(deps) {
|
|
30
|
+
const entries = [];
|
|
31
|
+
let tail = Promise.resolve();
|
|
32
|
+
async function runGates() {
|
|
33
|
+
// The gates registered when this pass's turn comes (one registered meanwhile applies to it too).
|
|
34
|
+
for (const entry of [...entries]) {
|
|
35
|
+
if (entry.satisfied || !entries.includes(entry))
|
|
36
|
+
continue;
|
|
37
|
+
if (deps.isDisposed())
|
|
38
|
+
throw new MarmotError('disposed', 'groups.create: client has been disposed');
|
|
39
|
+
const result = await deps.call(entry.gate);
|
|
40
|
+
if (reportsOnce(result))
|
|
41
|
+
entry.satisfied = true;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
return {
|
|
45
|
+
register(gate) {
|
|
46
|
+
if (typeof gate !== 'function')
|
|
47
|
+
throw new MarmotError('invalid-options', 'extensions.beforeCreateGroup: gate must be a function');
|
|
48
|
+
const entry = { gate, satisfied: false };
|
|
49
|
+
entries.push(entry);
|
|
50
|
+
return () => {
|
|
51
|
+
const i = entries.indexOf(entry);
|
|
52
|
+
if (i >= 0)
|
|
53
|
+
entries.splice(i, 1);
|
|
54
|
+
};
|
|
55
|
+
},
|
|
56
|
+
pass() {
|
|
57
|
+
// Every gate satisfied (or none registered): nothing to wait for.
|
|
58
|
+
if (entries.every((e) => e.satisfied))
|
|
59
|
+
return Promise.resolve();
|
|
60
|
+
const run = tail.then(runGates);
|
|
61
|
+
tail = run.catch(() => undefined);
|
|
62
|
+
return run;
|
|
63
|
+
},
|
|
64
|
+
};
|
|
65
|
+
}
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
import type { ClientState } from '@941design/marmot-engine/mls';
|
|
2
|
+
import { type RetainedWindow } from '../history/index.js';
|
|
3
|
+
import type { GroupStoreTx } from '../storage/index.js';
|
|
4
|
+
import { type GroupSnapshot } from './group-snapshot.js';
|
|
5
|
+
import type { ReentrancyGuard } from './reentrancy-guard.js';
|
|
6
|
+
/**
|
|
7
|
+
* Awaited by marmot after every `onBeforePublish` hook transaction committed and before the commit's first publish.
|
|
8
|
+
* Resolve when the backup is safe, reject when it could not be made; `signal` aborts when marmot stops waiting (the
|
|
9
|
+
* deadline passed, or the client ended) — a barrier must then stop work that could outlive its usefulness.
|
|
10
|
+
*/
|
|
11
|
+
export type PublishBarrier = (signal: AbortSignal) => Promise<void>;
|
|
12
|
+
/** What an `onBeforePublish` hook receives. `tx` is the hook's OWN transaction on the group's store. */
|
|
13
|
+
export interface BeforePublishContext {
|
|
14
|
+
readonly groupId: string;
|
|
15
|
+
/** The intent's id (what `ConfirmContext.intentId` will be at its confirmation). */
|
|
16
|
+
readonly intentId: string;
|
|
17
|
+
readonly kind: 'commit' | 'self-update';
|
|
18
|
+
/** Epoch of the state the commit produces. */
|
|
19
|
+
readonly epoch: bigint;
|
|
20
|
+
readonly commit: {
|
|
21
|
+
/** The staged envelope's Nostr event id. Never a stable identity of the commit: a re-encrypted copy has another id. */
|
|
22
|
+
readonly eventId: string;
|
|
23
|
+
/** Hex SHA-256 of the commit's MLS wire bytes (`commitDigest`): the commit's identity, and what the pending marker binds. */
|
|
24
|
+
readonly digest: string;
|
|
25
|
+
/** Hex confirmation tag of the state the commit was built from. */
|
|
26
|
+
readonly parentTag: string;
|
|
27
|
+
/** Hex confirmation tag of the state the commit produces. */
|
|
28
|
+
readonly tag: string;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* The hook's own transaction: its writes commit when the hook returns and roll back when it throws. Use it, never
|
|
32
|
+
* the store. The hook is unbounded in time and holds the group's queue: store writes only, no I/O (see the module
|
|
33
|
+
* comment); signer and relay calls belong in the returned {@link PublishBarrier}.
|
|
34
|
+
*/
|
|
35
|
+
readonly tx: GroupStoreTx;
|
|
36
|
+
/**
|
|
37
|
+
* The pending-tagged snapshot of the state the commit produces (payload kind `marmot.groupSnapshot.pending`,
|
|
38
|
+
* carrying `{ digest, parentTag }`; its window's tip edge is the commit from the parent). Built lazily on the first
|
|
39
|
+
* read and memoized; readable only while the hook runs — a first read after it returned throws `transaction-closed`.
|
|
40
|
+
* NOT ENCRYPTED, like every snapshot: it holds live key material.
|
|
41
|
+
*/
|
|
42
|
+
readonly snapshot: GroupSnapshot;
|
|
43
|
+
/** Set only for the commit `devices.forget` issues: the signature keys (hex) of the leaves it removes. Its backup stays on the confirm path. */
|
|
44
|
+
readonly forgetting?: {
|
|
45
|
+
readonly leafKeys: readonly string[];
|
|
46
|
+
};
|
|
47
|
+
/** `true` only when the hook runs for an envelope an earlier pass staged (the resume path or a publish retry timer), not the run that staged it. */
|
|
48
|
+
readonly resumed: boolean;
|
|
49
|
+
}
|
|
50
|
+
export type BeforePublishHook = (ctx: BeforePublishContext) => void | PublishBarrier | Promise<void | PublishBarrier>;
|
|
51
|
+
/** Why the commit went out without (all of) its pre-publish work. */
|
|
52
|
+
export type BeforePublishSkippedReason = 'hook-error' | 'barrier-failed' | 'barrier-timeout';
|
|
53
|
+
/** `beforePublishSkipped`: the commit was published although a hook threw, a barrier rejected or the deadline passed. */
|
|
54
|
+
export interface BeforePublishSkipped {
|
|
55
|
+
readonly groupId: string;
|
|
56
|
+
readonly intentId: string;
|
|
57
|
+
readonly reason: BeforePublishSkippedReason;
|
|
58
|
+
/** The hook's or the barrier's rejection; absent for `barrier-timeout`. */
|
|
59
|
+
readonly error?: unknown;
|
|
60
|
+
}
|
|
61
|
+
/** The client's `onBeforePublish` registry and its deadline. */
|
|
62
|
+
export interface BeforePublishRegistry {
|
|
63
|
+
/** `options.beforePublishTimeoutMs`. */
|
|
64
|
+
readonly timeoutMs: number;
|
|
65
|
+
/** The live hook list, in registration order. */
|
|
66
|
+
readonly hooks: readonly BeforePublishHook[];
|
|
67
|
+
/** Registers `hook`; returns its unregister function (idempotent). */
|
|
68
|
+
register(hook: BeforePublishHook): () => void;
|
|
69
|
+
/** Drops every hook (dispose). */
|
|
70
|
+
clear(): void;
|
|
71
|
+
}
|
|
72
|
+
export declare function createBeforePublishRegistry(timeoutMs: number): BeforePublishRegistry;
|
|
73
|
+
/** The scheduler the barrier deadline runs on (the client's injectable timers). */
|
|
74
|
+
export interface BeforePublishTimers {
|
|
75
|
+
set(callback: () => void, ms: number): unknown;
|
|
76
|
+
clear(handle: unknown): void;
|
|
77
|
+
}
|
|
78
|
+
export interface BeforePublishSite {
|
|
79
|
+
readonly groupId: string;
|
|
80
|
+
readonly guard: ReentrancyGuard;
|
|
81
|
+
/** The registry's live hook list (read once per run, in registration order). */
|
|
82
|
+
readonly hooks: readonly BeforePublishHook[];
|
|
83
|
+
readonly timeoutMs: number;
|
|
84
|
+
readonly timers: BeforePublishTimers;
|
|
85
|
+
/** One hook transaction on the group's store, framed on the group's `store` surface. */
|
|
86
|
+
transaction<T>(fn: (tx: GroupStoreTx) => Promise<T>): Promise<T>;
|
|
87
|
+
/** Emits `beforePublishSkipped`. */
|
|
88
|
+
skipped(event: BeforePublishSkipped): void;
|
|
89
|
+
/** Whether the group's runtime has ended (client disposed, group fenced or abandoned, stores lost their lease). */
|
|
90
|
+
ended(): boolean;
|
|
91
|
+
/**
|
|
92
|
+
* Registers `end` to be told once if the group's runtime ends while the barriers wait; returns its removal. The
|
|
93
|
+
* wait then stops at once, abandoning the barriers. Calls `end` at once when the runtime already ended.
|
|
94
|
+
*/
|
|
95
|
+
onRuntimeEnd(end: () => void): () => void;
|
|
96
|
+
}
|
|
97
|
+
/** One own commit, staged and about to be published. */
|
|
98
|
+
export interface BeforePublishRun {
|
|
99
|
+
readonly intentId: string;
|
|
100
|
+
readonly kind: 'commit' | 'self-update';
|
|
101
|
+
readonly envelopeId: string;
|
|
102
|
+
/** The staged commit's MLS wire bytes. */
|
|
103
|
+
readonly commitMessage: Uint8Array;
|
|
104
|
+
/** The state the commit was built from, and the state it produces (deserialized from the staged record). */
|
|
105
|
+
readonly parentState: ClientState;
|
|
106
|
+
readonly newState: ClientState;
|
|
107
|
+
/** The window `confirmRecord` would persist for this commit — called at most once, on the first `snapshot` read. */
|
|
108
|
+
readonly window: () => RetainedWindow;
|
|
109
|
+
/** The group's account-index `createdAt` (client-clock ms), when known. */
|
|
110
|
+
readonly createdAt: number | undefined;
|
|
111
|
+
readonly forgetting?: {
|
|
112
|
+
readonly leafKeys: readonly string[];
|
|
113
|
+
};
|
|
114
|
+
readonly resumed: boolean;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Runs every registered hook for `run`, then awaits the barriers they returned under one deadline. Never rejects for
|
|
118
|
+
* a hook or barrier failure (the commit is published whatever happens; `site.skipped` reports it); a disposal of the
|
|
119
|
+
* client propagates, like everywhere else in the settlement.
|
|
120
|
+
*/
|
|
121
|
+
export declare function runBeforePublish(site: BeforePublishSite, run: BeforePublishRun): Promise<'done' | 'ended'>;
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `extensions.onBeforePublish` (epic marmot-leaf-backup-pre-publish, AC-HOOK-*, AC-BAR-*): a hook between an own
|
|
3
|
+
* commit's staging and its FIRST publish, handed the pending-tagged {@link GroupSnapshot} of the state the commit
|
|
4
|
+
* produces, plus an optional bounded, best-effort {@link PublishBarrier} the commit's publish waits for.
|
|
5
|
+
*
|
|
6
|
+
* Unlike `onConfirm` (which runs INSIDE the persisting transaction and whose throw aborts it) this surface is
|
|
7
|
+
* best-effort by decision: each hook runs in its OWN group-store transaction, after the staging transaction
|
|
8
|
+
* committed, so a throw rolls back only that hook's writes and never the durable `pendingIntents` record; the
|
|
9
|
+
* commit is published whatever the hooks and barriers do (a `beforePublishSkipped` event reports it). Marmot alone
|
|
10
|
+
* publishes the commit (ADR-007): a hook never takes the commit's transaction nor publishes it.
|
|
11
|
+
*
|
|
12
|
+
* Contract:
|
|
13
|
+
* - runs for `commit` and `self-update` intents only (never an application message, a proposal, a create, a join,
|
|
14
|
+
* a foreign commit's ingest or a restore's adoption), once per staged envelope per runtime;
|
|
15
|
+
* - hooks run in registration order, each in its own transaction and `onBeforePublish` re-entrancy frame;
|
|
16
|
+
* - the barriers they return run AFTER every hook transaction committed, outside any storage transaction,
|
|
17
|
+
* concurrently under ONE deadline (`beforePublishTimeoutMs`); a rejection or the deadline abandons a barrier (its
|
|
18
|
+
* `signal` aborts) and the commit is published anyway;
|
|
19
|
+
* - `ctx.snapshot` is lazy (a hook that never reads it pays no serialization) and readable only while the hook runs.
|
|
20
|
+
*
|
|
21
|
+
* The hook is the DURABLE-WRITE half: it holds the group's queue and an open store transaction for as long as it
|
|
22
|
+
* runs, and nothing bounds it (a transaction cannot be abandoned safely mid-flight). A hook therefore does store
|
|
23
|
+
* writes through `ctx.tx` and CPU work only (read the snapshot, seal it, write a record), never signer, relay or
|
|
24
|
+
* other I/O. All I/O belongs in the `PublishBarrier` it returns, which runs outside any transaction under the
|
|
25
|
+
* deadline. Register hooks before the first group access: a commit staged or resumed earlier does not see a hook
|
|
26
|
+
* registered later.
|
|
27
|
+
*
|
|
28
|
+
* Hooks must be idempotent per `commit.digest`: a crash between staging and the hook is repaired by the resume path
|
|
29
|
+
* running the hook again (`resumed: true`).
|
|
30
|
+
*/
|
|
31
|
+
import { commitDigest } from '@941design/marmot-engine/core';
|
|
32
|
+
import { tagOf } from '../history/index.js';
|
|
33
|
+
import { hexOf } from '../history/hex.js';
|
|
34
|
+
import { MarmotError } from '../shared/index.js';
|
|
35
|
+
import { cursorFloor } from './confirm-hooks.js';
|
|
36
|
+
import { sealGroupSnapshot } from './group-snapshot.js';
|
|
37
|
+
export function createBeforePublishRegistry(timeoutMs) {
|
|
38
|
+
const hooks = [];
|
|
39
|
+
return {
|
|
40
|
+
timeoutMs,
|
|
41
|
+
hooks,
|
|
42
|
+
register(hook) {
|
|
43
|
+
if (typeof hook !== 'function')
|
|
44
|
+
throw new MarmotError('invalid-options', 'extensions.onBeforePublish: hook must be a function');
|
|
45
|
+
hooks.push(hook);
|
|
46
|
+
return () => {
|
|
47
|
+
const i = hooks.indexOf(hook);
|
|
48
|
+
if (i >= 0)
|
|
49
|
+
hooks.splice(i, 1);
|
|
50
|
+
};
|
|
51
|
+
},
|
|
52
|
+
clear() {
|
|
53
|
+
hooks.length = 0;
|
|
54
|
+
},
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Runs every registered hook for `run`, then awaits the barriers they returned under one deadline. Never rejects for
|
|
59
|
+
* a hook or barrier failure (the commit is published whatever happens; `site.skipped` reports it); a disposal of the
|
|
60
|
+
* client propagates, like everywhere else in the settlement.
|
|
61
|
+
*/
|
|
62
|
+
export async function runBeforePublish(site, run) {
|
|
63
|
+
const hooks = [...site.hooks];
|
|
64
|
+
if (hooks.length === 0)
|
|
65
|
+
return 'done';
|
|
66
|
+
const digest = hexOf(commitDigest(run.commitMessage));
|
|
67
|
+
const parentTag = tagOf(run.parentState);
|
|
68
|
+
const tag = tagOf(run.newState);
|
|
69
|
+
const epoch = run.newState.groupContext.epoch;
|
|
70
|
+
const barriers = [];
|
|
71
|
+
for (const hook of hooks) {
|
|
72
|
+
if (site.ended())
|
|
73
|
+
return 'ended';
|
|
74
|
+
let open = true;
|
|
75
|
+
let sealed;
|
|
76
|
+
let barrier;
|
|
77
|
+
try {
|
|
78
|
+
await site.transaction(async (tx) => {
|
|
79
|
+
const since = await cursorFloor(tx);
|
|
80
|
+
const snapshotOf = () => {
|
|
81
|
+
if (!open) {
|
|
82
|
+
throw new MarmotError('transaction-closed', 'BeforePublishContext.snapshot: read after the hook returned; read it inside the hook', {
|
|
83
|
+
details: { groupId: site.groupId, intentId: run.intentId },
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
if (sealed !== undefined)
|
|
87
|
+
return sealed;
|
|
88
|
+
sealed = sealGroupSnapshot({
|
|
89
|
+
groupId: site.groupId,
|
|
90
|
+
state: run.newState,
|
|
91
|
+
window: run.window(),
|
|
92
|
+
...(run.createdAt === undefined ? {} : { createdAt: run.createdAt }),
|
|
93
|
+
...(since === undefined ? {} : { since }),
|
|
94
|
+
pending: { digest, parentTag },
|
|
95
|
+
});
|
|
96
|
+
return sealed;
|
|
97
|
+
};
|
|
98
|
+
const ctx = {
|
|
99
|
+
groupId: site.groupId,
|
|
100
|
+
intentId: run.intentId,
|
|
101
|
+
kind: run.kind,
|
|
102
|
+
epoch,
|
|
103
|
+
commit: Object.freeze({ eventId: run.envelopeId, digest, parentTag, tag }),
|
|
104
|
+
tx,
|
|
105
|
+
get snapshot() {
|
|
106
|
+
return snapshotOf();
|
|
107
|
+
},
|
|
108
|
+
...(run.forgetting === undefined ? {} : { forgetting: { leafKeys: [...run.forgetting.leafKeys] } }),
|
|
109
|
+
resumed: run.resumed,
|
|
110
|
+
};
|
|
111
|
+
try {
|
|
112
|
+
const result = await site.guard.call(site.groupId, 'onBeforePublish', () => hook(ctx));
|
|
113
|
+
if (typeof result === 'function')
|
|
114
|
+
barrier = result;
|
|
115
|
+
}
|
|
116
|
+
finally {
|
|
117
|
+
open = false;
|
|
118
|
+
}
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
catch (error) {
|
|
122
|
+
// The hook's own transaction rolled back; the staged record and every other hook's writes stay.
|
|
123
|
+
if (error instanceof MarmotError && error.code === 'disposed')
|
|
124
|
+
throw error;
|
|
125
|
+
site.skipped({ groupId: site.groupId, intentId: run.intentId, reason: 'hook-error', error });
|
|
126
|
+
continue;
|
|
127
|
+
}
|
|
128
|
+
if (barrier !== undefined)
|
|
129
|
+
barriers.push(barrier);
|
|
130
|
+
}
|
|
131
|
+
// A runtime that ended during a hook (dispose, fence, lost lease) starts no barrier and arms no timer.
|
|
132
|
+
if (site.ended())
|
|
133
|
+
return 'ended';
|
|
134
|
+
if (barriers.length > 0)
|
|
135
|
+
await awaitBarriers(site, run.intentId, barriers);
|
|
136
|
+
return site.ended() ? 'ended' : 'done';
|
|
137
|
+
}
|
|
138
|
+
/** Awaits every barrier concurrently under the site's one deadline; resolves when all settled, the deadline passed or the runtime ended. */
|
|
139
|
+
function awaitBarriers(site, intentId, barriers) {
|
|
140
|
+
const abort = new AbortController();
|
|
141
|
+
return new Promise((resolve) => {
|
|
142
|
+
let finished = false;
|
|
143
|
+
let pending = barriers.length;
|
|
144
|
+
let timer;
|
|
145
|
+
let release = () => undefined;
|
|
146
|
+
const finish = () => {
|
|
147
|
+
if (finished)
|
|
148
|
+
return;
|
|
149
|
+
finished = true;
|
|
150
|
+
site.timers.clear(timer);
|
|
151
|
+
release();
|
|
152
|
+
resolve();
|
|
153
|
+
};
|
|
154
|
+
timer = site.timers.set(() => {
|
|
155
|
+
if (finished)
|
|
156
|
+
return;
|
|
157
|
+
abort.abort(new Error('onBeforePublish barrier: the beforePublishTimeoutMs deadline passed'));
|
|
158
|
+
site.skipped({ groupId: site.groupId, intentId, reason: 'barrier-timeout' });
|
|
159
|
+
finish();
|
|
160
|
+
}, site.timeoutMs);
|
|
161
|
+
release = site.onRuntimeEnd(() => {
|
|
162
|
+
abort.abort(new Error('onBeforePublish barrier: the group ended'));
|
|
163
|
+
finish();
|
|
164
|
+
});
|
|
165
|
+
for (const barrier of barriers) {
|
|
166
|
+
site.guard
|
|
167
|
+
.call(site.groupId, 'onBeforePublish', () => barrier(abort.signal))
|
|
168
|
+
.then(() => {
|
|
169
|
+
if (--pending === 0)
|
|
170
|
+
finish();
|
|
171
|
+
}, (error) => {
|
|
172
|
+
// A barrier that fails after the wait ended (deadline, runtime end) is already abandoned: nothing to report.
|
|
173
|
+
if (!finished)
|
|
174
|
+
site.skipped({ groupId: site.groupId, intentId, reason: 'barrier-failed', error });
|
|
175
|
+
if (--pending === 0)
|
|
176
|
+
finish();
|
|
177
|
+
});
|
|
178
|
+
}
|
|
179
|
+
});
|
|
180
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The engine seams every `marmot` group engine is built with (S8, S9; ADR-002
|
|
3
|
+
* seams, ADR-003, ADR-006, ADR-012): one place, so the engine that builds a
|
|
4
|
+
* commit and every engine that receives one — and the Welcome join
|
|
5
|
+
* (`clientConfig`) — agree (AC-VENDOR-6: a mismatched equality rule is a
|
|
6
|
+
* silent fork hazard).
|
|
7
|
+
*
|
|
8
|
+
* - `clientConfig`: {@link sameAccountClientConfig} — signature-key-only
|
|
9
|
+
* KeyPackage/leaf equality (AC-DEV-12 pins that the ts-mls default would
|
|
10
|
+
* refuse a same-account Add);
|
|
11
|
+
* - `authorizeCommit`: the admin rule's send-path half (S9: no SelfRemove
|
|
12
|
+
* of an admin account's last leaf) around the same-account rules over the
|
|
13
|
+
* engine's CURRENT tree (the commit's parent), read lazily through
|
|
14
|
+
* `ratchetTree`;
|
|
15
|
+
* - `adminPolicyCallback`: S3's proof gate around the same-account receive
|
|
16
|
+
* rules around S9's admin deviation (AC-ADMIN-4) around the vendored
|
|
17
|
+
* admin rule;
|
|
18
|
+
* - `isActiveAdminLeaver`: S9's "last active leaf of an admin account" for
|
|
19
|
+
* the engine's SelfRemove auto-commit election (AC-ADMIN-9).
|
|
20
|
+
*/
|
|
21
|
+
import type { decideCommitAuthorization } from '@941design/marmot-engine/core';
|
|
22
|
+
import type { ActiveAdminLeaverPredicate } from '@941design/marmot-engine/engine';
|
|
23
|
+
import type { ClientConfig, RatchetTree } from '@941design/marmot-engine/mls';
|
|
24
|
+
import { sameAccountClientConfig, type AdminPolicyFactory } from '../account/index.js';
|
|
25
|
+
/** An absent seam is the engine's own default (the vendored rule). */
|
|
26
|
+
export interface EngineSeams {
|
|
27
|
+
readonly clientConfig: ClientConfig;
|
|
28
|
+
readonly authorizeCommit: typeof decideCommitAuthorization | undefined;
|
|
29
|
+
readonly adminPolicyCallback: AdminPolicyFactory | undefined;
|
|
30
|
+
readonly isActiveAdminLeaver: ActiveAdminLeaverPredicate | undefined;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Internal (tests only, never part of `MarmotClientOptions`): rewrites the
|
|
34
|
+
* seams a client's engines get — how a test builds a client on the engine
|
|
35
|
+
* defaults to prove a seam is load-bearing (AC-ADMIN-8, AC-ADMIN-9).
|
|
36
|
+
*/
|
|
37
|
+
export type EngineSeamsOverride = (seams: EngineSeams) => EngineSeams;
|
|
38
|
+
/** The seams for one engine; `ratchetTree` returns that engine's current tree. */
|
|
39
|
+
export declare function engineSeams(ratchetTree: () => RatchetTree): EngineSeams;
|
|
40
|
+
export { sameAccountClientConfig };
|
|
41
|
+
/** The convergence policy every `marmot` engine runs — defined beside the rewind window's horizon (one source). */
|
|
42
|
+
export { MARMOT_CONVERGENCE_POLICY } from '../history/policy.js';
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { createAdminAuthorizeCommit, createAdminDeviationPolicy, createProofEnforcingAdminPolicy, createSameAccountAdminPolicy, createSameAccountAuthorizeCommit, isLastActiveLeafOfAdmin, sameAccountClientConfig, } from '../account/index.js';
|
|
2
|
+
/** The seams for one engine; `ratchetTree` returns that engine's current tree. */
|
|
3
|
+
export function engineSeams(ratchetTree) {
|
|
4
|
+
return {
|
|
5
|
+
clientConfig: sameAccountClientConfig,
|
|
6
|
+
authorizeCommit: createAdminAuthorizeCommit(createSameAccountAuthorizeCommit(ratchetTree), ratchetTree),
|
|
7
|
+
adminPolicyCallback: createProofEnforcingAdminPolicy(createSameAccountAdminPolicy(createAdminDeviationPolicy())),
|
|
8
|
+
isActiveAdminLeaver: isLastActiveLeafOfAdmin,
|
|
9
|
+
};
|
|
10
|
+
}
|
|
11
|
+
export { sameAccountClientConfig };
|
|
12
|
+
/** The convergence policy every `marmot` engine runs — defined beside the rewind window's horizon (one source). */
|
|
13
|
+
export { MARMOT_CONVERGENCE_POLICY } from '../history/policy.js';
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { ClientState } from '@941design/marmot-engine/mls';
|
|
2
|
+
import { type OwnChange, type OwnChangeLostReason, type RetainedWindow } from '../history/index.js';
|
|
3
|
+
import type { StorableIntent, StoredOwnChange } from './group-records.js';
|
|
4
|
+
/** The facts the checks read: the tip the commit will be built on and the window the lineage evidence lives in. */
|
|
5
|
+
export interface RedriveFacts {
|
|
6
|
+
/** The engine's tip state: the tree the commit is built on. */
|
|
7
|
+
readonly state: ClientState;
|
|
8
|
+
/** The retained rewind window, and its own tip state (the exposed one). */
|
|
9
|
+
readonly window: RetainedWindow;
|
|
10
|
+
readonly windowTip: ClientState;
|
|
11
|
+
/** Whether the author's ACCOUNT is an active admin at `state` (`isActiveAdmin`, rotation-proof). */
|
|
12
|
+
readonly authorIsAdmin: boolean;
|
|
13
|
+
/** The fork-point epoch the record's changes were captured at. */
|
|
14
|
+
readonly forkEpoch: number;
|
|
15
|
+
/**
|
|
16
|
+
* The refs (`inviteeRef`) of the stored KeyPackages the invitations path no longer accepts at build time (`validateInvitees`:
|
|
17
|
+
* expired, rejected by the verifier, ineligible for the group). Decided by the drive, which owns the clock and the verifier; the
|
|
18
|
+
* ladder only reads it. Required: a caller that cannot say must not look as if every KeyPackage is valid.
|
|
19
|
+
*/
|
|
20
|
+
readonly invalidKeyPackages: ReadonlySet<string>;
|
|
21
|
+
}
|
|
22
|
+
/** What the surviving changes of one kind add to the intent the commit is built from (never stored: DD15). */
|
|
23
|
+
export type RedriveContribution = Partial<Pick<Extract<StorableIntent, {
|
|
24
|
+
type: 'commit';
|
|
25
|
+
}>, 'removeAccounts' | 'removeAccountLeafKeys' | 'admins' | 'components' | 'invite'>>;
|
|
26
|
+
/** The part of the ladder that is specific to one kind of change. */
|
|
27
|
+
export interface RedriveChangeKind<C extends StoredOwnChange> {
|
|
28
|
+
/** The reason `change` is lost at `facts`, or `undefined` when it still applies. Decided from the change's fork-point values and the current state. */
|
|
29
|
+
readonly check: (change: C, facts: RedriveFacts) => OwnChangeLostReason | undefined;
|
|
30
|
+
/**
|
|
31
|
+
* For a kind whose survivors depend on one another: the further changes of `survivors` (all of this kind that passed `check`) that
|
|
32
|
+
* cannot be applied TOGETHER, with their reasons. Optional; run once, before `contribute`, over the survivors of `check`.
|
|
33
|
+
*/
|
|
34
|
+
readonly checkSet?: (survivors: readonly C[], facts: RedriveFacts) => ReadonlyMap<C, OwnChangeLostReason>;
|
|
35
|
+
/** What `survivors` (all of this kind, at least one) add to the commit to build. */
|
|
36
|
+
readonly contribute: (survivors: readonly C[], facts: RedriveFacts) => RedriveContribution;
|
|
37
|
+
}
|
|
38
|
+
type OfKind<K extends OwnChange['type']> = Extract<StoredOwnChange, {
|
|
39
|
+
readonly change: {
|
|
40
|
+
readonly type: K;
|
|
41
|
+
};
|
|
42
|
+
}>;
|
|
43
|
+
/**
|
|
44
|
+
* The invite changes whose KeyPackage the drive must still check (the facts' `invalidKeyPackages`): undecided, the author an
|
|
45
|
+
* admin, and neither already applied nor reversed -- the ladder would reach the validity rung for exactly these, so a consumer
|
|
46
|
+
* verifier is never called for a change that is lost anyway. Pure.
|
|
47
|
+
*/
|
|
48
|
+
export declare function changesNeedingKeyPackageCheck(stored: readonly StoredOwnChange[], facts: Omit<RedriveFacts, 'invalidKeyPackages'>): readonly OfKind<'member-added'>[];
|
|
49
|
+
/** The handlers by change type: every kind has one, so a change is never lost for want of a handler. */
|
|
50
|
+
export declare const REDRIVE_CHANGE_KINDS: {
|
|
51
|
+
readonly [K in OwnChange['type']]: RedriveChangeKind<OfKind<K>>;
|
|
52
|
+
};
|
|
53
|
+
/** The verdicts of one ladder run. */
|
|
54
|
+
export interface LadderOutcome {
|
|
55
|
+
/** Every change of the record, in order: those decided lost in an EARLIER run keep their verdict; those lost now gain it; survivors have none. */
|
|
56
|
+
readonly changes: readonly StoredOwnChange[];
|
|
57
|
+
/** The changes lost by THIS run (the ones to signal): earlier verdicts were persisted, and signalled, before. */
|
|
58
|
+
readonly newlyLost: readonly {
|
|
59
|
+
readonly change: OwnChange;
|
|
60
|
+
readonly reason: OwnChangeLostReason;
|
|
61
|
+
}[];
|
|
62
|
+
readonly survivors: readonly StoredOwnChange[];
|
|
63
|
+
/** The kinds' contributions merged: the payload of the commit to build. Empty when nothing survives. */
|
|
64
|
+
readonly contribution: RedriveContribution;
|
|
65
|
+
}
|
|
66
|
+
/** Runs rungs 2 and 3 of the ladder over `stored` (rung 1, stranded, never reaches here). Pure. */
|
|
67
|
+
export declare function decideChanges(stored: readonly StoredOwnChange[], facts: RedriveFacts): LadderOutcome;
|
|
68
|
+
export {};
|