keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/cli/messaging/multisig.js

@@ -0,0 +1,569 @@
+import { action, spawn } from "effection";
+import { resolveDelegationCommunicationHab } from "../../app/identity/delegating.js";
+import { endpointRoleAccepted, groupSigningMembers, isLocalGroupHab, localGroupMember, proposeGroupEndpointRole, } from "../../app/identity/endpoint-roleing.js";
+import { uniqueMembers } from "../../app/multisig/group-members.js";
+import { MULTISIG_ICP_ROUTE, MULTISIG_IXN_ROUTE, MULTISIG_REV_ROUTE, MULTISIG_ROT_ROUTE, MULTISIG_VCP_ROUTE, } from "../../app/multisig/grouping.js";
+import { approvePendingMultisigProposal, commitAcceptedGroupMembers, eventAccepted, publishProposal, routeForKelEvent, } from "../../app/multisig/multisig-workflows.js";
+import { runAgentRuntime } from "../../app/runtime/agent-runtime.js";
+import { Receiptor, WitnessReceiptor } from "../../app/witness/receipting.js";
+import { ValidationError } from "../../core/errors.js";
+import { Roles } from "../../core/roles.js";
+import { withAgentRuntime } from "../common/context.js";
+import { loadOptionObject, loadRotateFileOptions, parseBooleanOption, parseCountOption, parseDataItems, parseFileData, parseKeriVersionOption, parseNumberOption, parseStringListOption, parseStringOption, parseThresholdOption, } from "../common/parsing.js";
+import { waitForIssuedCredential, waitForTelPublication } from "../common/tel-completion.js";
+import { resolveWitnessAuths } from "../common/witness-auth.js";
+const MULTISIG_TOPIC = "multisig";
+function requireText(value, label) {
+    if (!value) {
+        throw new ValidationError(`${label} is required and cannot be empty`);
+    }
+    return value;
+}
+/** Validate every supplied group member and policy field before opening the group store. */
+function loadMultisigInceptFile(path) {
+    const loaded = loadOptionObject(path);
+    return {
+        aids: parseStringListOption(loaded.aids, "aids"),
+        rmids: parseStringListOption(loaded.rmids, "rmids"),
+        isith: parseThresholdOption(loaded.isith),
+        nsith: parseThresholdOption(loaded.nsith),
+        toad: parseCountOption(loaded.toad, "toad"),
+        wits: parseStringListOption(loaded.wits, "wits"),
+        data: parseFileData(loaded.data),
+        delpre: parseStringOption(loaded.delpre, "delpre"),
+    };
+}
+/** Create or begin a distributed group identifier from a KLI-style file. */
+export function* multisigInceptCommand(args) {
+    const commandArgs = {
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        group: parseStringOption(args.group, "group"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        endpoint: parseBooleanOption(args.endpoint, "endpoint"),
+        authenticate: parseBooleanOption(args.authenticate, "authenticate"),
+        code: parseStringListOption(args.code, "code"),
+        codeTime: parseStringOption(args.codeTime, "codeTime"),
+        file: parseStringOption(args.file, "file"),
+        approvalTimeoutSeconds: nonNegativeNumber(args.approvalTimeoutSeconds, 10, "approval timeout seconds"),
+        proxy: parseStringOption(args.proxy, "proxy"),
+        version: parseKeriVersionOption(args.version),
+    };
+    const name = requireText(commandArgs.name, "Name");
+    const alias = requireText(commandArgs.alias, "Alias");
+    const group = requireText(commandArgs.group, "Group");
+    const file = requireText(commandArgs.file, "Config file");
+    const options = loadMultisigInceptFile(file);
+    const smids = options.aids ?? [];
+    const rmids = options.rmids ?? smids;
+    if (smids.length === 0) {
+        throw new ValidationError("Multisig inception config must include non-empty aids.");
+    }
+    return yield* withMultisigRuntime(commandArgs, name, function* ({ hby, runtime }) {
+        const member = requireHabByAlias(hby, alias);
+        const created = hby.makeGroupHab(group, member, smids, rmids, undefined, {
+            isith: options.isith,
+            nsith: options.nsith,
+            toad: options.toad,
+            wits: options.wits ?? [],
+            delpre: options.delpre,
+            data: options.data ?? [],
+            version: commandArgs.version,
+        });
+        const { deliveries, messages } = yield* publishProposal(hby, runtime.protocol, runtime.postman, member, uniqueMembers([...smids, ...rmids]), {
+            route: MULTISIG_ICP_ROUTE,
+            attrs: { smids, rmids, ...(options.delpre ? { delegator: options.delpre } : {}) },
+        }, created.message);
+        const accepted = yield* waitForGroupAcceptance(hby, runtime, created.serder, multisigApprovalOptions(hby, {
+            ...commandArgs,
+            group,
+            auto: true,
+        }));
+        let delegationPhase = null;
+        if (accepted) {
+            yield* receiptAcceptedEvent(hby, created.hab.pre, commandArgs, runtime);
+            delegationPhase = yield* completeDelegationIfNeeded(hby, runtime, created.hab.pre, commandArgs.proxy);
+        }
+        return {
+            route: MULTISIG_ICP_ROUTE,
+            group: created.hab.pre,
+            accepted,
+            messages,
+            deliveries,
+            state: hby.db.getState(created.hab.pre),
+            delegationPhase: delegationPhase,
+        };
+    });
+}
+/** Poll for and approve one pending group multisig event. */
+export function* multisigJoinCommand(args) {
+    const commandArgs = {
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        group: parseStringOption(args.group, "group"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        endpoint: parseBooleanOption(args.endpoint, "endpoint"),
+        authenticate: parseBooleanOption(args.authenticate, "authenticate"),
+        code: parseStringListOption(args.code, "code"),
+        codeTime: parseStringOption(args.codeTime, "codeTime"),
+        auto: parseBooleanOption(args.auto, "auto"),
+        registryName: parseStringOption(args.registryName, "registryName"),
+        said: parseStringOption(args.said, "said"),
+        approvalTimeoutSeconds: nonNegativeNumber(args.approvalTimeoutSeconds, 60, "approval timeout seconds"),
+        proxy: parseStringOption(args.proxy, "proxy"),
+    };
+    const name = requireText(commandArgs.name, "Name");
+    return yield* withMultisigRuntime(commandArgs, name, function* ({ hby, runtime }) {
+        const approval = multisigApprovalOptions(hby, commandArgs);
+        const result = yield* waitForOneApproval(hby, runtime, approval);
+        if (!result) {
+            const local = yield* waitForLocalGroupCompletion(hby, runtime, approval);
+            if (!local) {
+                throw new ValidationError("No matching stored multisig proposal was available to join.");
+            }
+            if (local.accepted) {
+                yield* receiptAcceptedEvent(hby, local.group, commandArgs, runtime);
+                if (local.route === MULTISIG_ICP_ROUTE || local.route === MULTISIG_ROT_ROUTE) {
+                    yield* completeDelegationIfNeeded(hby, runtime, local.group, commandArgs.proxy);
+                }
+            }
+            return local;
+        }
+        if (result.tel) {
+            const { publication, reger } = runtime.vdr;
+            const tel = result.tel;
+            if (result.route === MULTISIG_VCP_ROUTE || result.route === MULTISIG_REV_ROUTE) {
+                yield* waitForTelPublication(publication, tel.pre, tel.sn, approval.deadline);
+                result.accepted = reger.tels.getOn(tel.pre, tel.sn)?.qb64 === result.embedded;
+            }
+            else {
+                yield* waitForIssuedCredential(publication, tel.pre, approval.deadline);
+                result.accepted = reger.saved.get(tel.pre) !== null;
+            }
+            tel.publicationComplete = publication.complete(tel.pre, tel.sn);
+            return result;
+        }
+        if (result.accepted) {
+            yield* receiptAcceptedEvent(hby, result.group, commandArgs, runtime);
+            if (result.route === MULTISIG_ICP_ROUTE
+                || result.route === MULTISIG_ROT_ROUTE) {
+                yield* completeDelegationIfNeeded(hby, runtime, result.group, commandArgs.proxy);
+            }
+        }
+        return result;
+    });
+}
+/** Create or begin one group interaction event. */
+export function* multisigInteractCommand(args) {
+    const commandArgs = {
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        group: parseStringOption(args.group, "group"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        endpoint: parseBooleanOption(args.endpoint, "endpoint"),
+        authenticate: parseBooleanOption(args.authenticate, "authenticate"),
+        code: parseStringListOption(args.code, "code"),
+        codeTime: parseStringOption(args.codeTime, "codeTime"),
+        data: parseStringListOption(args.data, "data"),
+        approvalTimeoutSeconds: nonNegativeNumber(args.approvalTimeoutSeconds, 10, "approval timeout seconds"),
+        version: parseKeriVersionOption(args.version),
+    };
+    const name = requireText(commandArgs.name, "Name");
+    const group = requireText(commandArgs.group ?? commandArgs.alias, "Group");
+    const data = parseDataItems(commandArgs.data);
+    return yield* withMultisigRuntime(commandArgs, name, function* ({ hby, runtime }) {
+        const created = hby.interactGroupHab(group, undefined, { data, version: commandArgs.version });
+        const smids = groupSigningMembers(hby, created.hab.pre);
+        const { deliveries, messages } = yield* publishProposal(hby, runtime.protocol, runtime.postman, localGroupMember(hby, created.hab.pre), smids, { route: MULTISIG_IXN_ROUTE, attrs: { gid: created.hab.pre, smids } }, created.message);
+        const accepted = yield* waitForGroupAcceptance(hby, runtime, created.serder, multisigApprovalOptions(hby, {
+            ...commandArgs,
+            group,
+            auto: true,
+        }));
+        if (accepted) {
+            yield* receiptAcceptedEvent(hby, created.hab.pre, commandArgs, runtime);
+        }
+        return {
+            route: MULTISIG_IXN_ROUTE,
+            group: created.hab.pre,
+            accepted,
+            messages,
+            deliveries,
+            state: hby.db.getState(created.hab.pre),
+            delegationPhase: null,
+        };
+    });
+}
+/** Rotate or begin rotation of one group identifier. */
+export function* multisigRotateCommand(args) {
+    const commandArgs = {
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        group: parseStringOption(args.group, "group"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        endpoint: parseBooleanOption(args.endpoint, "endpoint"),
+        authenticate: parseBooleanOption(args.authenticate, "authenticate"),
+        code: parseStringListOption(args.code, "code"),
+        codeTime: parseStringOption(args.codeTime, "codeTime"),
+        file: parseStringOption(args.file, "file"),
+        isith: parseThresholdOption(args.isith),
+        nsith: parseThresholdOption(args.nsith),
+        toad: parseCountOption(args.toad, "toad"),
+        witnesses: parseStringListOption(args.witnesses, "witnesses"),
+        cuts: parseStringListOption(args.cuts, "cuts"),
+        witnessAdd: parseStringListOption(args.witnessAdd, "witnessAdd"),
+        data: parseStringListOption(args.data, "data"),
+        smids: parseStringListOption(args.smids, "smids"),
+        rmids: parseStringListOption(args.rmids, "rmids"),
+        proxy: parseStringOption(args.proxy, "proxy"),
+        approvalTimeoutSeconds: nonNegativeNumber(args.approvalTimeoutSeconds, 10, "approval timeout seconds"),
+        version: parseKeriVersionOption(args.version),
+    };
+    const name = requireText(commandArgs.name, "Name");
+    const group = requireText(commandArgs.group ?? commandArgs.alias, "Group");
+    const options = mergeRotateOptions(commandArgs);
+    return yield* withMultisigRuntime(commandArgs, name, function* ({ hby, runtime }) {
+        const rotated = hby.rotateGroupHab(group, commandArgs.smids, commandArgs.rmids, {
+            isith: options.isith,
+            nsith: options.nsith,
+            toad: options.toad,
+            cuts: options.witsCut,
+            adds: options.witsAdd,
+            data: options.data ?? [],
+            version: commandArgs.version,
+        });
+        const smids = commandArgs.smids?.length ? commandArgs.smids : groupSigningMembers(hby, rotated.hab.pre);
+        const rmids = commandArgs.rmids?.length ? commandArgs.rmids : smids;
+        const { deliveries, messages } = yield* publishProposal(hby, runtime.protocol, runtime.postman, localGroupMember(hby, rotated.hab.pre), uniqueMembers([...smids, ...rmids]), { route: MULTISIG_ROT_ROUTE, attrs: { gid: rotated.hab.pre, smids, rmids } }, rotated.message);
+        const accepted = yield* waitForGroupAcceptance(hby, runtime, rotated.serder, multisigApprovalOptions(hby, {
+            ...commandArgs,
+            group,
+            auto: true,
+        }));
+        let delegationPhase = null;
+        if (accepted) {
+            // The proposer's own acceptance must commit the rotated membership as a joiner's does.
+            commitAcceptedGroupMembers(hby, rotated.serder, smids, rmids);
+            yield* receiptAcceptedEvent(hby, rotated.hab.pre, commandArgs, runtime);
+            delegationPhase = yield* completeDelegationIfNeeded(hby, runtime, rotated.hab.pre, commandArgs.proxy);
+        }
+        return {
+            route: MULTISIG_ROT_ROUTE,
+            group: rotated.hab.pre,
+            accepted,
+            messages,
+            deliveries,
+            state: hby.db.getState(rotated.hab.pre),
+            delegationPhase: delegationPhase,
+        };
+    });
+}
+/** Propose one group multisig reply such as `/end/role/add`. */
+export function* multisigRpyCommand(args) {
+    const commandArgs = {
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        group: parseStringOption(args.group, "group"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        eid: parseStringOption(args.eid, "eid"),
+        role: parseStringOption(args.role, "role"),
+        allow: parseBooleanOption(args.allow, "allow"),
+        approvalTimeoutSeconds: nonNegativeNumber(args.approvalTimeoutSeconds, 0, "approval timeout seconds"),
+    };
+    const name = requireText(commandArgs.name, "Name");
+    const group = requireText(commandArgs.group ?? commandArgs.alias, "Group");
+    const eid = requireText(commandArgs.eid, "Endpoint identifier");
+    const role = commandArgs.role ?? Roles.mailbox;
+    return yield* withMultisigRuntime(commandArgs, name, function* ({ hby, runtime }) {
+        const groupHab = requireHabByAlias(hby, group);
+        const result = yield* proposeGroupEndpointRole(hby, runtime.protocol, runtime.postman, groupHab, { eid, role, allow: commandArgs.allow });
+        const accepted = commandArgs.approvalTimeoutSeconds > 0
+            ? yield* waitForReplyAcceptance(hby, runtime, groupHab.pre, role, eid, multisigApprovalOptions(hby, {
+                ...commandArgs,
+                group: groupHab.pre,
+                auto: true,
+            }))
+            : result.accepted;
+        return { ...result, accepted };
+    });
+}
+function* withMultisigRuntime(args, name, use) {
+    return yield* withAgentRuntime({ ...args, name }, {
+        compat: args.compat ?? false,
+        readonly: false,
+        skipConfig: true,
+        skipSignator: false,
+    }, function* (context) {
+        const selector = args.alias ?? args.group;
+        const selected = selector ? context.hby.habByName(selector) ?? context.hby.habs.get(selector) : undefined;
+        const signer = selected && isLocalGroupHab(context.hby, selected)
+            ? localGroupMember(context.hby, selected.pre)
+            : selected;
+        const worker = yield* spawn(() => runAgentRuntime(context.runtime, { hab: signer }));
+        try {
+            return yield* use(context);
+        }
+        finally {
+            yield* worker.halt();
+        }
+    });
+}
+function requireHabByAlias(hby, alias) {
+    const hab = hby.habByName(alias);
+    if (!hab?.pre) {
+        throw new ValidationError(`Alias ${alias} is invalid`);
+    }
+    return hab;
+}
+function mergeRotateOptions(args) {
+    const options = args.file && args.file !== "" ? loadRotateFileOptions(args.file) : {};
+    if (args.isith !== undefined) {
+        options.isith = args.isith;
+    }
+    if (args.nsith !== undefined) {
+        options.nsith = args.nsith;
+    }
+    if (args.toad !== undefined) {
+        options.toad = args.toad;
+    }
+    if (args.witnesses !== undefined) {
+        options.wits = [...args.witnesses];
+    }
+    if (args.cuts !== undefined) {
+        options.witsCut = [...args.cuts];
+    }
+    if (args.witnessAdd !== undefined) {
+        options.witsAdd = [...args.witnessAdd];
+    }
+    if (args.data !== undefined) {
+        options.data = parseDataItems(args.data);
+    }
+    if ((options.wits?.length ?? 0) > 0) {
+        throw new ValidationError("multisig rotate does not accept replacement --witnesses yet; use --witness-cut/--witness-add.");
+    }
+    return options;
+}
+function multisigApprovalOptions(hby, args) {
+    // An existing group constrains approval; a new alias only names the group
+    // after its inception proposal is selected and approved.
+    return {
+        group: args.group ? groupHabByAliasOrPrefix(hby, args.group)?.pre : undefined,
+        said: args.said,
+        deadline: Date.now() + args.approvalTimeoutSeconds * 1000,
+        callbacks: multisigApprovalCallbacks(hby, args),
+    };
+}
+function multisigApprovalCallbacks(hby, args) {
+    return {
+        approveProposal: (context) => approvePrompt(args, context),
+        chooseGroupAlias: (groupPre) => chooseGroupAlias(hby, args, groupPre),
+        chooseRegistryName: (regk) => chooseRegistryName(args, regk),
+    };
+}
+function chooseRegistryName(args, regk) {
+    if (args.registryName) {
+        return args.registryName;
+    }
+    if (args.auto) {
+        return `registry-${regk.slice(0, 12)}`;
+    }
+    while (true) {
+        const name = prompt("\nName for Registry: ")?.trim();
+        if (name) {
+            return name;
+        }
+    }
+}
+function chooseGroupAlias(hby, args, groupPre) {
+    if (args.group) {
+        return args.group;
+    }
+    const record = hby.db.getHab(groupPre);
+    if (record?.name) {
+        return record.name;
+    }
+    if (args.auto) {
+        return "default-group";
+    }
+    while (true) {
+        const group = prompt("\nEnter group name for new AID: ")?.trim();
+        if (!group) {
+            continue;
+        }
+        const existing = hby.db.getName("", group);
+        if (existing && existing !== groupPre) {
+            console.log(`AID group name ${group} is already in use, please try again`);
+            continue;
+        }
+        return group;
+    }
+}
+function approvePrompt(args, context) {
+    if (args.auto) {
+        return true;
+    }
+    console.log(JSON.stringify({
+        route: context.route,
+        group: context.group,
+        embedded: context.embedded,
+    }, null, 2));
+    const yn = prompt("\nJoin [Y|n]? ");
+    return yn === null || yn === "" || yn === "y" || yn === "Y";
+}
+/**
+ * Collect witness receipts for the current accepted multisig event using explicit runtime collaborators.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param pre Accepted group event subject.
+ * @param args Witness authentication and HTTP endpoint mode choices.
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ */
+function* receiptAcceptedEvent(hby, pre, args, runtime) {
+    const kever = hby.db.getKever(pre);
+    if (!kever || kever.wits.length === 0) {
+        return;
+    }
+    const auths = resolveWitnessAuths(kever.wits, args.code ?? [], {
+        codeTime: args.codeTime,
+        promptMissing: args.authenticate ?? false,
+    });
+    if (args.endpoint) {
+        const receiptor = new Receiptor(hby, runtime.protocol, runtime.http, runtime.clock);
+        yield* receiptor.receipt(pre, { sn: kever.sn, auths });
+    }
+    else {
+        const witDoer = new WitnessReceiptor(hby, runtime.protocol, runtime.http, runtime.clock);
+        yield* witDoer.submit(pre, { sn: kever.sn, auths });
+    }
+}
+/** Approval waits allow fractional seconds and zero, but never coerce absence or overflow a deadline. */
+function nonNegativeNumber(value, fallback, label) {
+    const parsed = parseNumberOption(value, label) ?? fallback;
+    if (parsed < 0 || !Number.isFinite(parsed * 1000)) {
+        throw new ValidationError(`${label} must be a finite nonnegative duration.`);
+    }
+    return parsed;
+}
+/** Approve stored proposals until the target event is accepted or the deadline expires. */
+function* waitForGroupAcceptance(hby, runtime, serder, options) {
+    if (eventAccepted(hby, serder)) {
+        return true;
+    }
+    while (true) {
+        yield* approvePendingMultisigProposal(hby, runtime, options);
+        if (eventAccepted(hby, serder)) {
+            return true;
+        }
+        if (Date.now() >= options.deadline)
+            break;
+        yield* sleep(Math.min(250, options.deadline - Date.now()));
+    }
+    return eventAccepted(hby, serder);
+}
+/** Wait for one stored proposal while the command host owns background progress. */
+function* waitForOneApproval(hby, runtime, options) {
+    while (true) {
+        const result = yield* approvePendingMultisigProposal(hby, runtime, options);
+        if (result) {
+            return result;
+        }
+        if (Date.now() >= options.deadline)
+            break;
+        yield* sleep(Math.min(250, options.deadline - Date.now()));
+    }
+    return null;
+}
+/** Wait for a locally authored group event to complete through stored approvals. */
+function* waitForLocalGroupCompletion(hby, runtime, options) {
+    if (!options.group || options.said) {
+        return null;
+    }
+    const groupHab = groupHabByAliasOrPrefix(hby, options.group);
+    if (!groupHab?.pre) {
+        return null;
+    }
+    const serder = localGroupJoinSerder(hby, groupHab.pre);
+    if (!serder) {
+        return null;
+    }
+    const route = routeForKelEvent(serder);
+    if (!route) {
+        return null;
+    }
+    const accepted = yield* waitForGroupAcceptance(hby, runtime, serder, options);
+    return {
+        route,
+        said: "",
+        embedded: serder.said ?? "",
+        group: groupHab.pre,
+        accepted,
+        deliveries: [],
+        messages: [],
+    };
+}
+/** Approve stored proposals until the endpoint reply is accepted or the deadline expires. */
+function* waitForReplyAcceptance(hby, runtime, groupPre, role, eid, options) {
+    if (endpointRoleAccepted(hby, groupPre, role, eid)) {
+        return true;
+    }
+    while (true) {
+        yield* approvePendingMultisigProposal(hby, runtime, options);
+        if (endpointRoleAccepted(hby, groupPre, role, eid)) {
+            return true;
+        }
+        if (Date.now() >= options.deadline)
+            break;
+        yield* sleep(Math.min(250, options.deadline - Date.now()));
+    }
+    return endpointRoleAccepted(hby, groupPre, role, eid);
+}
+/** Complete the delegation workflow for an accepted delegated group event. */
+function* completeDelegationIfNeeded(hby, runtime, pre, proxy) {
+    const kever = hby.db.getKever(pre);
+    if (!kever?.delpre) {
+        return null;
+    }
+    const communicationHab = resolveDelegationCommunicationHab(hby, proxy);
+    if (!communicationHab) {
+        throw new ValidationError(`Delegated group event for ${pre} requires --proxy <alias>.`);
+    }
+    runtime.delegating.beginLatest(pre, kever.sn, { communicationHab });
+    const deadline = Date.now() + 120_000;
+    while (!runtime.delegating.complete(pre, kever.sn)) {
+        if (Date.now() >= deadline)
+            throw new Error("Runtime did not converge within 120000ms.");
+        yield* sleep(Math.min(250, deadline - Date.now()));
+    }
+    return runtime.delegating.workflowStatus(pre, kever.sner.numh).phase;
+}
+function groupHabByAliasOrPrefix(hby, group) {
+    return hby.habByName(group) ?? hby.habs.get(group) ?? null;
+}
+function localGroupJoinSerder(hby, groupPre) {
+    const kever = hby.db.getKever(groupPre);
+    if (kever?.serder) {
+        return kever.serder;
+    }
+    return hby.db.getEvtSerder(groupPre, groupPre);
+}
+function* sleep(ms) {
+    yield* action((resolve) => {
+        const id = setTimeout(resolve, ms);
+        return () => clearTimeout(id);
+    });
+}

package/esm/keri/npm/src/{app/cli → cli/messaging}/notifications.js

@@ -1,6 +1,7 @@
+import { Notifier, openNoterForHabery } from "../../app/notifications/notifying.js";
 import { ValidationError } from "../../core/errors.js";
-import { Notifier, openNoterForHabery } from "../notifying.js";
-import { withExistingHabery } from "./common/context.js";
+import { withExistingHabery } from "../common/context.js";
+import { parseBooleanOption, parseCountOption, parseStringOption } from "../common/parsing.js";
 function requireName(name) {
     if (!name) {
         throw new ValidationError("Name is required and cannot be empty");
@@ -22,8 +23,11 @@ function* withNotifier(args, use) {
         skipConfig: true,
         skipSignator: false,
     }, function* ({ hby }) {
+        const signator = hby.signator;
+        if (!signator)
+            throw new ValidationError("Notifications require an available habery signator.");
         const noter = yield* openNoterForHabery(hby);
-        const notifier = new Notifier(hby, { noter });
+        const notifier = new Notifier(signator, { noter });
         try {
             return yield* use({ notifier });
         }
@@ -38,13 +42,13 @@ function* withNotifier(args, use) {
 /** Print verified local controller notices as JSON for operator inspection. */
 export function* notificationsListCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        compat: args.compat,
-        start: args.start,
-        limit: args.limit,
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        start: parseCountOption(args.start, "start"),
+        limit: parseCountOption(args.limit, "limit"),
     };
     yield* withNotifier(commandArgs, function* ({ notifier }) {
         const start = commandArgs.start ?? 0;
@@ -66,12 +70,12 @@ export function* notificationsListCommand(args) {
 /** Mark one verified notice as read and persist its new detached signature. */
 export function* notificationsMarkReadCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        compat: args.compat,
-        rid: args.rid,
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        rid: parseStringOption(args.rid, "rid"),
     };
     yield* withNotifier(commandArgs, function* ({ notifier }) {
         const rid = requireRid(commandArgs.rid);
@@ -82,12 +86,12 @@ export function* notificationsMarkReadCommand(args) {
 /** Remove one verified notice from the notification sidecar. */
 export function* notificationsRemoveCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        compat: args.compat,
-        rid: args.rid,
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        compat: parseBooleanOption(args.compat, "compat"),
+        rid: parseStringOption(args.rid, "rid"),
     };
     yield* withNotifier(commandArgs, function* ({ notifier }) {
         const rid = requireRid(commandArgs.rid);

package/esm/keri/npm/src/{app/cli → cli}/output.js

@@ -1,5 +1,5 @@
 /** Own stdout writes until completion or cancellation, including partial native writes. */
-import * as dntShim from "../../_dnt.shims.js";
+import * as dntShim from "../_dnt.shims.js";
 export async function writeStdout(text, signal) {
     const bytes = new TextEncoder().encode(text);
     /** The CLI owns stdout; closing it interrupts a blocked native write on scope cancellation. */

package/esm/keri/npm/src/cli/tools/annotate.js

@@ -0,0 +1,25 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { annotate } from "cesr-ts";
+import { abortable } from "../../app/runtime/abortable.js";
+import { collectBytes, fileBytes, streamBytes } from "../../app/transport/byte-source.js";
+import { parseBooleanOption, parseStringOption } from "../common/parsing.js";
+import { writeStdout } from "../output.js";
+import { colorizeAnnotatedOutput } from "./annotate-color.js";
+/** Annotate bounded file/stdin input with every I/O leaf owned by this operation. */
+export function* annotateCommand(args) {
+    const options = {
+        inPath: parseStringOption(args.inPath, "inPath"),
+        outPath: parseStringOption(args.outPath, "outPath"),
+        pretty: parseBooleanOption(args.pretty, "pretty"),
+        colored: parseBooleanOption(args.colored, "colored"),
+    };
+    const bytes = yield* abortable((signal) => collectBytes(options.inPath ? fileBytes(options.inPath, { signal }) : streamBytes(dntShim.Deno.stdin.readable, { signal })));
+    const text = annotate(bytes, { pretty: options.pretty });
+    if (options.outPath) {
+        yield* abortable((signal) => dntShim.Deno.writeTextFile(options.outPath, text, { signal }));
+    }
+    else {
+        const output = options.colored ? colorizeAnnotatedOutput(text) : text;
+        yield* abortable((signal) => writeStdout(`${output}\n`, signal));
+    }
+}