keri-ts 2.1.0 → 2.2.0

package/esm/keri/npm/src/cli/messaging/group-wait.js

@@ -0,0 +1,88 @@
+/**
+ * What a group command does after it has proposed or approved an event: give the
+ * Counselor the user's choices and wait on it. Nothing here signs; the only call
+ * that signs a proposal is `approveGroupProposal`, which `group-join.ts` makes for
+ * the one proposal the user chose. A proposer's wait therefore cannot sign any
+ * other stored proposal.
+ */
+import { Ilks } from "cesr-ts";
+import { resolveDelegationCommunicationHab } from "../../app/identity/delegating.js";
+import { DELEGATION_WAIT_TIMEOUT_MS } from "../../app/identity/event-completion.js";
+import { waitForGroupEvent, } from "../../app/multisig/counseling.js";
+import { observeUntil } from "../../app/runtime/workflow-contract.js";
+import { ValidationError } from "../../core/errors.js";
+import { resolveWitnessAuths } from "../common/witness-auth.js";
+/** The local hab that sends a delegated group event's traffic; the user must name it. */
+export function delegationProxy(hby, alias, label) {
+    const proxy = resolveDelegationCommunicationHab(hby, alias);
+    if (!proxy)
+        throw new ValidationError(`Delegated group event for ${label} requires --proxy <alias>.`);
+    return proxy;
+}
+/**
+ * Counselor inputs for a proposed event. `fallbackAfterMs: 0` makes every member
+ * submit witness receipts and publish the delegation request, as this command
+ * always has; KERIpy's `kli` elects one member and the others only fetch.
+ */
+export function counselInputs(hby, proxy, delegated = false, label = "") {
+    return { fallbackAfterMs: 0, ...(delegated ? { proxy: delegationProxy(hby, proxy, label) } : {}) };
+}
+/** Wait until the exact event is accepted here, replaced at its sn, or the deadline passes. */
+export function* waitForAcceptance(hby, runtime, event, deadline) {
+    const accepted = () => hby.db.kels.getLast(event.pre, event.sn) === event.said;
+    yield* observeUntil(() => accepted() || runtime.counselor.status(event).state === "superseded", { timeoutMs: Math.max(0, deadline - Date.now()), pollMs: 50 });
+    return accepted();
+}
+/** Witness Authorization values for the group's current witnesses, as `--code`/`--authenticate` choose. */
+export function witnessAuths(hby, pre, args) {
+    const kever = hby.db.getKever(pre);
+    if (!kever || kever.wits.length === 0)
+        return undefined;
+    return resolveWitnessAuths(kever.wits, args.code ?? [], {
+        codeTime: args.codeTime,
+        promptMissing: args.authenticate ?? false,
+    });
+}
+/** Give a counseled event this command's witness authorizations; memory only. */
+export function supplyWitnessAuths(hby, runtime, event, args) {
+    const auths = event && witnessAuths(hby, event.pre, args);
+    if (event && auths)
+        runtime.counselor.supply(event, { auths });
+}
+/** Give a delegated event just approved here its proxy; other events need none. */
+export function supplyDelegationProxy(hby, runtime, event, alias) {
+    const ilk = hby.db.getEvtSerder(event.pre, event.said)?.ilk;
+    if (ilk !== Ilks.dip && ilk !== Ilks.drt)
+        return;
+    runtime.counselor.supply(event, { proxy: delegationProxy(hby, alias, event.pre) });
+}
+/**
+ * Wait for the Counselor to complete an accepted event: witness receipts and,
+ * for a delegated event, the delegator's approval.
+ *
+ * @returns The delegation phase for a delegated inception or rotation, else null.
+ */
+export function* finishAcceptedEvent(hby, runtime, event, args) {
+    supplyWitnessAuths(hby, runtime, event, args);
+    const waited = yield* waitForGroupEvent(runtime.counselor, event, { timeoutMs: DELEGATION_WAIT_TIMEOUT_MS });
+    if (waited.outcome === "timed-out")
+        throw new Error(stalledMessage(event, waited.status));
+    const kever = hby.db.getKever(event.pre);
+    const ilk = hby.db.getEvtSerder(event.pre, event.said)?.ilk;
+    return kever?.delpre && (ilk === Ilks.dip || ilk === Ilks.drt)
+        ? runtime.delegating.workflowStatus(event.pre, kever.sner.numh).phase
+        : null;
+}
+function stalledMessage(event, status) {
+    const blocked = status.state === "pending" ? status.blocked : undefined;
+    const why = !blocked
+        ? `still waiting at ${status.state === "pending" ? status.stage : status.state}`
+        : blocked.kind === "witnessAuth"
+            ? `witness authorization is required for ${blocked.witnesses.join(", ")}`
+            : blocked.kind === "witness"
+                ? blocked.reason
+                : blocked.kind === "delegatorUnknown"
+                    ? `delegator ${blocked.delpre} is unknown`
+                    : "delegation is not supported by this host";
+    return `Group event ${event.pre} sn=${event.sn} did not complete within ${DELEGATION_WAIT_TIMEOUT_MS}ms: ${why}.`;
+}