keri-ts 2.0.1 → 2.2.0

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

@@ -0,0 +1,79 @@
+/**
+ * `tufa multisig join` proposal selection, as KERIpy `kli multisig join`.
+ *
+ * Join approves exactly one stored proposal, the first the user consents to:
+ * - an explicit `--said` names the proposal, otherwise the unapproved proposals
+ *   the notice store announces are offered in notice order;
+ * - without `--auto` every offered proposal is shown and approved only on a yes;
+ * - with `--auto` the first offered proposal is approved without a prompt. This is
+ *   the whole of auto consent: it exists only inside the `join` the user ran for
+ *   that purpose, and no other command signs a proposal it was not asked to sign.
+ *
+ * Signing, publication and the Counselor hand-off belong to `approveGroupProposal`.
+ */
+import { sleep } from "effection";
+import { approveGroupProposal, dismissGroupProposal, findGroupProposal, listGroupProposals, } from "../../app/multisig/proposals.js";
+import { ValidationError } from "../../core/errors.js";
+/** Group prefix for a joined group's prefix or alias; undefined for a name not yet used. */
+function joinedGroup(hby, group) {
+    return group === undefined ? undefined : (hby.habByName(group) ?? hby.habs.get(group))?.pre ?? undefined;
+}
+/** Candidates for one pass, oldest first. */
+function candidates(deps, { said, group }) {
+    const wanted = joinedGroup(deps.hby, group);
+    if (said !== undefined) {
+        const proposal = findGroupProposal(deps, said);
+        if (proposal && wanted !== undefined && proposal.group !== wanted) {
+            throw new ValidationError(`Multisig exchange ${said} belongs to group ${proposal.group}, not ${wanted}.`);
+        }
+        return proposal ? [proposal] : [];
+    }
+    return listGroupProposals(deps, wanted === undefined ? {} : { group: wanted })
+        .filter(proposal => proposal.local === "unapproved");
+}
+/**
+ * Approve the first proposal the user consents to, polling stored proposals until
+ * the deadline. A declined proposal is not offered again by this call. Returns
+ * null when nothing was approved; the host owns the runtime that delivers new
+ * proposals while this waits.
+ */
+export function* joinProposal(deps, options) {
+    if (!deps.notifier && options.said === undefined) {
+        throw new ValidationError("Multisig join requires notification storage or an explicit exchange SAID.");
+    }
+    const skipped = new Set();
+    while (true) {
+        for (const proposal of candidates(deps, options)) {
+            if (skipped.has(proposal.said))
+                continue;
+            // An explicit proposal already approved here is replayed without asking again.
+            if (proposal.local !== "approved" && !options.confirm(proposal)) {
+                skipped.add(proposal.said);
+                continue;
+            }
+            const choices = { ...options.inputs(proposal) };
+            if (proposal.needs.groupAlias)
+                choices.groupAlias = options.groupAlias(proposal);
+            if (proposal.needs.registryName)
+                choices.registryName = options.registryName(proposal);
+            let result;
+            try {
+                result = yield* approveGroupProposal(deps, proposal.said, choices);
+            }
+            catch (error) {
+                // A proposal that cannot be approved never hides a later one; an explicit SAID reports why.
+                if (options.said === undefined && error instanceof ValidationError) {
+                    skipped.add(proposal.said);
+                    continue;
+                }
+                throw error;
+            }
+            dismissGroupProposal(deps, proposal.said);
+            return { proposal, result };
+        }
+        const remaining = options.deadline - Date.now();
+        if (remaining <= 0)
+            return null;
+        yield* sleep(Math.min(250, remaining));
+    }
+}

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}.`;
+}