keri-ts 2.0.1 → 2.2.0

package/esm/keri/npm/src/app/multisig/multisig-workflows.js

@@ -2,33 +2,35 @@ import { Organizer } from "../identity/organizing.js";
 /**
  * Multisig proposal and approval workflows.
  *
- * CLI orchestration owns timed waits, worker lifetimes, prompts and output.
  * This module publishes proposals and approves stored KEL/RPY/VDR proposals
- * without starting or driving background workers.
+ * without starting or driving background workers. `approveGroupProposal` is the
+ * only caller that approves; it never asks, because calling it is the consent.
  */
-import { attachmentPayload, collectPayload, concatBytes, Counter, Diger, Ilks, NumberPrimitive, NumDex, parseBytes, Prefixer, SerderACDC, SerderKERI, TraitDex, Vrsn_2_0, } from "cesr-ts";
+import { attachmentPayload, collectPayload, concatBytes, Counter, Diger, Ilks, NumberPrimitive, NumDex, parseBytes, Prefixer, SerderACDC, SerderKERI, TraitDex, Verfer, Vrsn_2_0, } from "cesr-ts";
 import { verifyRegistryAnchor, vetBlind, } from "../../acdc/regeventing.js";
 import { publicOpeningAttachment } from "../../acdc/registering.js";
 import { ValidationError } from "../../core/errors.js";
-import { isV2RegistryRoute } from "../../core/exchange/protocol-exchanging.js";
 import { Kever } from "../../core/kel/kever.js";
 import { messagize } from "../../core/protocol-serialization.js";
 import { RegistryRecord } from "../../core/records.js";
+import { dgKey } from "../../db/core/keys.js";
 import { loadNests } from "../../db/exchange/exchange-nests.js";
 import { Credentialer, Registry, serializeCredential } from "../../vdr/credentialing.js";
 import { envelopeFromFrame } from "../protocol/parsering.js";
 import { groupCredentialAnchorReady, validateCredentialIssueProposal, validateCredentialRevocationProposal, validateCredentialSource, validateRegistryName, validateRegistryProposal, } from "../credentials/credential-proposals.js";
+import { telEventStatus } from "../credentials/tel-completion.js";
 import { endpointRoleAccepted, groupEndorseReply, groupEventKeys, groupSigningMembers, localGroupMember, signLocalGroupEvent, } from "../identity/endpoint-roleing.js";
 import { Reactor } from "../protocol/reactor.js";
 import { abortable } from "../runtime/abortable.js";
 import { collectBytes } from "../transport/byte-source.js";
 import { findLocalGroupMember as findLocalMember, groupMemberHasKey, uniqueMembers } from "./group-members.js";
 import { acdcV2RegistryProposal, MULTISIG_ICP_ROUTE, MULTISIG_ISS_ROUTE, MULTISIG_IXN_ROUTE, MULTISIG_REV_ROUTE, MULTISIG_ROT_ROUTE, MULTISIG_RPY_ROUTE, MULTISIG_VCP_ROUTE, multisigChild, multisigChildEvidence, multisigChildGenusAttrs, prepareAcdcV2RegistryExn, prepareMultisigEventExn, prepareMultisigVdrExn, registryProposalEvent, } from "./grouping.js";
-import { admitAndSendGroupMessage, groupSendResult, multisigPayloadSaid, prepareGroupMessage, remoteGroupMembers, signGroupMessage, storedGroupMessage, } from "./multisig-messaging.js";
+import { admitAndSendGroupMessage, groupSendResult, prepareGroupMessage, remoteGroupMembers, signGroupMessage, storedGroupMessage, } from "./multisig-messaging.js";
 /** Approve one exact ACDC v2 TEL/anchor through existing member signing and ordinary processors.
  * A returned wrapper records consent, not quorum/witness/TEL completion; retry the accepted-state owners.
+ * `resume` reuses this member's recorded anchor signatures after a crash instead of signing again.
  */
-export function* approveAcdcV2Registry(hby, protocol, group, event, { anchor, opening } = {}) {
+export function* approveAcdcV2Registry(hby, protocol, group, event, { anchor, opening, resume } = {}) {
     const registry = protocol.registry, member = localGroupMember(hby, group.pre);
     if (!registry || group.db !== hby.db || registry.db !== hby.db) {
         throw new ValidationError("ACDC v2 group registry owner is unavailable.");
@@ -105,7 +107,10 @@ export function* approveAcdcV2Registry(hby, protocol, group, event, { anchor, op
         throw new ValidationError("Registry anchor does not extend the current group event.");
     }
     const keys = groupEventKeys(hby, group.pre, anchor);
-    const sigers = signLocalGroupEvent(hby, anchor, groupSigningMembers(hby, group.pre), keys);
+    const members = groupSigningMembers(hby, group.pre);
+    // A resuming caller reuses the signatures the first attempt recorded in `sigs.` instead of signing the anchor again.
+    const sigers = (resume ? recordedLocalSignatures(hby, anchor, group.pre, members) : null)
+        ?? signLocalGroupEvent(hby, anchor, members, keys);
     const own = messagize(anchor, { sigers, gvrsn: Vrsn_2_0 });
     const tel = concatBytes(event.raw, Counter.enclose({
         code: "AttachmentGroup",
@@ -152,9 +157,10 @@ export function* publishAcdcV2Registry(hby, postman, group, approval) {
  * @param proposal Route-correlated group proposal with its named business fields.
  * @param embeddedMessage Signed child wire to include under the route-derived label.
  * @param childGvrsn Optional explicit attachment genus for the child.
+ * @param wrapperVersion Optional wrapper protocol version; an approval mirrors its proposal's.
  * @returns Stable proposal/wrapper identities and completed deliveries, independent of group acceptance.
  */
-export function* publishProposal(hby, protocol, postman, member, recipients, proposal, embeddedMessage, childGvrsn) {
+export function* publishProposal(hby, protocol, postman, member, recipients, proposal, embeddedMessage, childGvrsn, wrapperVersion) {
     const input = new Reactor(protocol);
     const outcomes = [];
     for (const recipient of remoteGroupMembers(hby, member, recipients)) {
@@ -162,6 +168,7 @@ export function* publishProposal(hby, protocol, postman, member, recipients, pro
         const prepared = yield* prepareMultisigEventExn(member.pre, proposal, embeddedMessage, {
             recipient: destination,
             childGvrsn,
+            ...(wrapperVersion ? { pvrsn: wrapperVersion } : {}),
         });
         const signed = yield* prepareGroupMessage(protocol.exc, member, destination, prepared);
         outcomes.push(yield* admitAndSendGroupMessage(input, postman, signed));
@@ -220,109 +227,34 @@ export function routeForKelEvent(serder) {
     }
 }
 /**
- * Select accepted coordination evidence before any approval effects.
- * An explicit SAID names the outer EXN and survives notification consumption.
- * Notices discover candidates; their attributes do not authorize a route or group.
- * An explicit accepted wrapper missing its handler index is replayed by the caller.
+ * Approve and publish this member's contribution to one `rip` or `bup` proposal.
+ * Null when the proposal is not a well-formed one for a joined group; it then stays inert.
  */
-function* pendingMultisigProposals(hby, runtime, notices, options) {
-    const candidates = options.said ? [options.said] : notices.map(note => note.attrs.d);
-    const group = options.group && (hby.habByName(options.group)?.pre ?? options.group);
-    const selected = [];
-    for (const said of new Set(candidates)) {
-        if (typeof said !== "string")
-            continue;
-        const exn = hby.db.exns.get([said]);
-        if (!exn?.ked)
-            continue;
-        const route = exn.route ?? "";
-        if (!isKelRoute(route) && !isVdrRoute(route) && route !== MULTISIG_RPY_ROUTE && !isV2RegistryRoute(route)) {
-            continue;
-        }
-        const payloadSaid = multisigPayloadSaid(exn);
-        if (!payloadSaid)
-            continue;
-        const indexed = hby.db.meids.get([payloadSaid]).some(index => index.qb64 === said);
-        if (!indexed && !options.said)
-            continue;
-        const proposalGroup = isKelRoute(route)
-            ? kelApproval(exn, route, yield* kelChild(hby, runtime, exn, route))?.group
-            : stringField(payloadSection(exn.ked), "gid");
-        if (!proposalGroup)
-            continue;
-        if (group && group !== proposalGroup) {
-            if (options.said) {
-                throw new ValidationError(`Multisig exchange ${said} belongs to group ${proposalGroup}, not ${group}.`);
-            }
-            continue;
-        }
-        selected.push({ exn, route, indexed });
-    }
-    return selected;
-}
-/** Approve matching stored evidence; host progress and deadlines belong to the caller. */
-export function* approvePendingMultisigProposal(hby, runtime, options) {
-    const notifier = runtime.notifier;
-    if (!notifier && !options.said) {
-        throw new ValidationError("Multisig join requires notification storage or an explicit exchange SAID.");
-    }
-    const notices = (notifier?.list(0, 100) ?? []);
-    for (const { exn, route, indexed } of yield* pendingMultisigProposals(hby, runtime, notices, options)) {
-        if (!indexed) {
-            // Acceptance commits before the asynchronous handler. Resume that ordinary
-            // authenticated intake after interruption; never synthesize approval indexes.
-            const message = yield* abortable(signal => collectBytes(runtime.exc.replay(exn.said, signal)));
-            yield* runtime.reactor.processBytes(message, { local: true });
-            const payloadSaid = multisigPayloadSaid(exn);
-            if (!hby.db.meids.get([payloadSaid]).some(index => index.qb64 === exn.said))
-                continue;
-        }
-        const rgy = isVdrRoute(route) ? runtime.vdr : null;
-        let result;
-        if (isKelRoute(route)) {
-            result = yield* approveKelProposal(hby, runtime, exn, route, options);
-        }
-        else if (isVdrRoute(route)) {
-            result = yield* approveVdrProposal(hby, rgy, runtime, exn, route, options);
-        }
-        else if (isV2RegistryRoute(route)) {
-            const nests = loadNests(hby.db, exn.said);
-            const proposal = acdcV2RegistryProposal(exn, nests, runtime.acdc?.store ?? null);
-            const group = proposal?.anchor.pre ? hby.habs.get(proposal.anchor.pre) : null;
-            if (!proposal || !group)
-                continue;
-            const head = group.kever?.serder.said;
-            if (!head)
-                throw new ValidationError("Registry approval requires an accepted local group.");
-            if (!options.callbacks.approveProposal({ route, group: group.pre, embedded: proposal.tel.said }))
-                continue;
-            if (group.kever?.serder.said !== head || !acdcV2RegistryProposal(exn, nests, runtime.acdc?.store ?? null)) {
-                throw new ValidationError("Group or registry changed while approval was pending.");
-            }
-            const envelope = envelopeFromFrame(nests[0]), opening = [...envelope.bsqs, ...envelope.bsss];
-            if (opening.length > 1)
-                throw new ValidationError("Registry proposal carries multiple openings.");
-            const approval = yield* approveAcdcV2Registry(hby, runtime.protocol, group, proposal.tel, {
-                anchor: proposal.anchor,
-                opening: opening[0],
-            });
-            const published = yield* publishAcdcV2Registry(hby, runtime.postman, group, approval);
-            const regid = proposal.tel.ilk === "rip" ? proposal.tel.said : proposal.tel.regid;
-            const accepted = runtime.acdc.store.seqEvent(regid, Number(BigInt(`0x${proposal.tel.sad.n}`)))?.said === proposal.tel.said;
-            result = { route, said: exn.said, embedded: proposal.tel.said, group: group.pre, accepted, ...published };
-        }
-        else {
-            result = yield* approveRpyProposal(hby, runtime, exn, route, options);
-        }
-        if (result) {
-            for (const note of notices) {
-                if (note.attrs.d === exn.said)
-                    notifier?.remove(note.rid);
-            }
-            return result;
-        }
-    }
-    return null;
+export function* approveRegistryV2Proposal(hby, runtime, exn, route, options) {
+    const nests = loadNests(hby.db, exn.said);
+    const proposal = acdcV2RegistryProposal(exn, nests, runtime.registryStore);
+    const group = proposal?.anchor.pre ? hby.habs.get(proposal.anchor.pre) : null;
+    if (!proposal || !group)
+        return null;
+    const head = group.kever?.serder.said;
+    if (!head)
+        throw new ValidationError("Registry approval requires an accepted local group.");
+    if (group.kever?.serder.said !== head || !acdcV2RegistryProposal(exn, nests, runtime.registryStore)) {
+        throw new ValidationError("Group or registry changed while approval was pending.");
+    }
+    const envelope = envelopeFromFrame(nests[0]), opening = [...envelope.bsqs, ...envelope.bsss];
+    if (opening.length > 1)
+        throw new ValidationError("Registry proposal carries multiple openings.");
+    const approval = yield* approveAcdcV2Registry(hby, runtime.protocol, group, proposal.tel, {
+        anchor: proposal.anchor,
+        opening: opening[0],
+        resume: options.resume,
+    });
+    const published = yield* publishAcdcV2Registry(hby, runtime.postman, group, approval);
+    const regid = proposal.tel.ilk === "rip" ? proposal.tel.said : proposal.tel.regid;
+    const accepted = runtime.registryStore?.seqEvent(regid, Number(BigInt(`0x${proposal.tel.sad.n}`)))?.said
+        === proposal.tel.said;
+    return { route, said: exn.said, embedded: proposal.tel.said, group: group.pre, accepted, ...published };
 }
 /**
  * Approve and publish a local contribution to one endpoint-role reply proposal.
@@ -333,10 +265,10 @@ export function* approvePendingMultisigProposal(hby, runtime, options) {
  * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
  * @param exn Stored multisig exchange wrapper.
  * @param route Selected multisig route identifying the proposal kind.
- * @param options Human approval/alias callbacks and workflow choices; refusal leaves the proposal inert.
+ * @param options Alias and name choices plus `resume`; a proposal that is not well formed is left inert.
  * @returns Approval result with protocol acceptance and deliveries, or null for declined/incomplete input.
  */
-function* approveRpyProposal(hby, runtime, exn, route, options) {
+export function* approveRpyProposal(hby, runtime, exn, route, options) {
     const wrapperSaid = exn.said;
     if (!wrapperSaid) {
         return null;
@@ -354,9 +286,6 @@ function* approveRpyProposal(hby, runtime, exn, route, options) {
     const { event: rpySerder, attachment, genus } = child;
     const embeddedSaid = rpySerder.said ?? "";
     const prior = storedGroupMessage(hby.db, member.pre, exn);
-    if (!prior && !options.callbacks.approveProposal({ route, group: groupPre, embedded: embeddedSaid || "<unknown>" })) {
-        return null;
-    }
     yield* runtime.reactor.processBytes(concatBytes(Counter.makeGVC(genus), rpySerder.raw, attachment), { local: true });
     let localRpy;
     if (prior) {
@@ -384,10 +313,10 @@ function* approveRpyProposal(hby, runtime, exn, route, options) {
  * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
  * @param exn Stored multisig exchange wrapper.
  * @param route Selected multisig route identifying the proposal kind.
- * @param options Human approval/alias callbacks and workflow choices; refusal leaves the proposal inert.
+ * @param options Alias and name choices plus `resume`; a proposal that is not well formed is left inert.
  * @returns Approval result with protocol acceptance and deliveries, or null for declined/incomplete input.
  */
-function* approveKelProposal(hby, runtime, exn, route, options) {
+export function* approveKelProposal(hby, runtime, exn, route, options) {
     const wrapperSaid = exn.said;
     if (!wrapperSaid) {
         return null;
@@ -427,24 +356,36 @@ function* approveKelProposal(hby, runtime, exn, route, options) {
         if (eventAccepted(hby, serder) && !smids.some(mid => hby.habs.has(mid))) {
             return null;
         }
-        if (!options.callbacks.approveProposal({ route, group: groupPre, embedded: embeddedSaid ?? "<unknown>" })) {
-            return null;
+        // Signing writes the member's signatures to `sigs.` when the event is first
+        // processed, before any wrapper exists. A resuming caller (explicit consent
+        // already given) finds them and reuses them: no second signature and no
+        // second join.
+        const signed = options.resume ? recordedLocalSignatures(hby, serder, groupPre, smids) : null;
+        if (signed) {
+            localMessage = messagize(serder, { sigers: signed, pipelined: false, gvrsn: approval.genus });
         }
-        if (proposal.route === MULTISIG_ICP_ROUTE || (proposal.route === MULTISIG_ROT_ROUTE && !hby.habs.has(groupPre))) {
-            const rmids = proposal.attrs.rmids;
-            const alias = options.callbacks.chooseGroupAlias(groupPre);
-            hby.joinGroupHab(groupPre, alias, member, smids, rmids.length > 0 ? rmids : smids);
+        else {
+            if (proposal.route === MULTISIG_ICP_ROUTE || (proposal.route === MULTISIG_ROT_ROUTE && !hby.habs.has(groupPre))) {
+                const rmids = proposal.attrs.rmids;
+                const alias = options.groupAlias;
+                if (!alias)
+                    throw new ValidationError(`A group alias is required to join ${groupPre}.`);
+                hby.joinGroupHab(groupPre, alias, member, smids, rmids.length > 0 ? rmids : smids);
+            }
+            const keys = groupEventKeys(hby, groupPre, serder);
+            const sigers = signLocalGroupEvent(hby, serder, smids, keys);
+            localMessage = messagize(serder, { sigers, pipelined: false, gvrsn: approval.genus });
         }
-        const keys = groupEventKeys(hby, groupPre, serder);
-        const sigers = signLocalGroupEvent(hby, serder, smids, keys);
-        localMessage = messagize(serder, { sigers, pipelined: false, gvrsn: approval.genus });
     }
     // Each contribution may already own a counted attachment enclosure. Admit
     // complete messages separately and let the ordinary KEL owner union proofs.
     yield* runtime.reactor.processBytes(concatBytes(Counter.makeGVC(approval.genus), localMessage), { local: true });
     yield* runtime.reactor.processBytes(concatBytes(Counter.makeGVC(approval.genus), serder.raw, approval.attachment), { local: true });
     yield* runtime.protocol.processEscrowsOnce();
-    const publication = yield* publishProposal(hby, runtime.protocol, runtime.postman, member, members, proposal, localMessage, approval.genus);
+    const publication = yield* publishProposal(hby, runtime.protocol, runtime.postman, member, members, proposal, localMessage, approval.genus, 
+    // KERIpy indexes contributions by wrapper form (v1 `e` SAID, v2 child SAID), so an
+    // approval must reuse its proposal's wrapper version for the proposer to merge it.
+    exn.pvrsn);
     const accepted = eventAccepted(hby, serder);
     if (proposal.route !== MULTISIG_IXN_ROUTE) {
         commitAcceptedGroupMembers(hby, serder, smids, proposal.attrs.rmids);
@@ -461,10 +402,10 @@ function* approveKelProposal(hby, runtime, exn, route, options) {
  * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
  * @param exn Stored multisig exchange wrapper.
  * @param route Selected multisig route identifying the proposal kind.
- * @param options Human approval/alias callbacks and workflow choices; refusal leaves the proposal inert.
+ * @param options Alias and name choices plus `resume`; a proposal that is not well formed is left inert.
  * @returns Approval result with protocol acceptance and deliveries, or null for declined/incomplete input.
  */
-function* approveVdrProposal(hby, rgy, runtime, exn, route, options) {
+export function* approveVdrProposal(hby, rgy, runtime, exn, route, options) {
     const wrapperSaid = exn.said;
     if (!wrapperSaid) {
         return null;
@@ -522,15 +463,14 @@ function* approveVdrProposal(hby, rgy, runtime, exn, route, options) {
     const prior = storedGroupMessage(hby.db, member.pre, exn);
     if (!prior && !groupCredentialAnchorReady(hby, groupPre, anchorSerder))
         return null;
-    if (!prior && !options.callbacks.approveProposal({ route, group: groupPre, embedded: embeddedSaid || "<unknown>" })) {
-        return null;
-    }
-    // Declined or malformed proposals remain inert; require VDR before signing or intake.
+    // Malformed proposals remain inert; require VDR before signing or intake.
     if (!rgy)
         throw new ValidationError("Legacy credential registry is unavailable in this runtime.");
     let registryName;
     if (proposal.route === MULTISIG_VCP_ROUTE && !prior) {
-        registryName = options.callbacks.chooseRegistryName(embeddedSerder.pre);
+        registryName = options.registryName;
+        if (!registryName)
+            throw new ValidationError(`A registry name is required for ${embeddedSerder.pre}.`);
         validateRegistryName(rgy.reger, registryName, embeddedSerder.pre);
     }
     const smids = groupSigningMembers(hby, groupPre);
@@ -540,7 +480,8 @@ function* approveVdrProposal(hby, rgy, runtime, exn, route, options) {
     }
     else {
         const keys = groupEventKeys(hby, groupPre, anchorSerder);
-        const sigers = signLocalGroupEvent(hby, anchorSerder, smids, keys);
+        const sigers = (options.resume ? recordedLocalSignatures(hby, anchorSerder, groupPre, smids) : null)
+            ?? signLocalGroupEvent(hby, anchorSerder, smids, keys);
         localAnchor = messagize(anchorSerder, { sigers, pipelined: false, gvrsn: genus });
     }
     yield* runtime.reactor.processBytes(concatBytes(Counter.makeGVC(genus), localAnchor), { local: true });
@@ -595,13 +536,32 @@ function* approveVdrProposal(hby, rgy, runtime, exn, route, options) {
         tel: {
             pre: embeddedSerder.pre,
             sn: embeddedSerder.sn,
-            publicationComplete: rgy.publication.complete(embeddedSerder.pre, embeddedSerder.sn),
+            publicationComplete: telEventStatus({ publication: rgy.publication }, embeddedSerder.pre, embeddedSerder.sn).state === "complete",
         },
         ...published,
     };
 }
+/**
+ * This process's verified signatures for a group event, one per local signing
+ * member, read from `sigs.`; null unless every local member's key index has one.
+ * Remote members' signatures in the same row never count.
+ */
+function recordedLocalSignatures(hby, serder, groupPre, smids) {
+    if (!hby.habs.has(groupPre) || !serder.pre || !serder.said)
+        return null;
+    const local = smids.flatMap((mid, index) => hby.habs.has(mid) ? [index] : []);
+    const stored = hby.db.sigs.get(dgKey(serder.pre, serder.said));
+    if (local.length === 0 || stored.length === 0)
+        return null;
+    const verfers = groupEventKeys(hby, groupPre, serder).map(qb64 => new Verfer({ qb64 }));
+    const { sigers } = Kever.verifyIndexedSignatures(serder.raw, stored, verfers);
+    const own = sigers.filter(siger => local.includes(siger.index));
+    return local.every(index => own.some(siger => siger.index === index))
+        ? own.sort((left, right) => left.index - right.index)
+        : null;
+}
 /** Preserve the recorded signing/rotation participant order during approval and resume. */
-function kelApprovalMembers({ proposal }) {
+export function kelApprovalMembers({ proposal }) {
     if (proposal.route === MULTISIG_IXN_ROUTE)
         return [...proposal.attrs.smids];
     return uniqueMembers([...proposal.attrs.smids, ...proposal.attrs.rmids]);
@@ -657,7 +617,7 @@ function kelProposalLabel(route) {
     }
 }
 /** Decode the fields used by approval, preserving existing missing-embed and member-list behavior. */
-function kelApproval(exn, route, child) {
+export function kelApproval(exn, route, child) {
     if (!child)
         return null;
     const { event } = child;
@@ -786,7 +746,7 @@ function rpyAttrs(serder) {
     }
     return { cid: attrs.cid, role: attrs.role, eid: attrs.eid };
 }
-function payloadSection(ked) {
+export function payloadSection(ked) {
     return isRecord(ked.a) ? ked.a : {};
 }
 function embeddedSection(ked) {
@@ -807,10 +767,10 @@ function stringField(record, field) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isKelRoute(route) {
+export function isKelRoute(route) {
     return route === MULTISIG_ICP_ROUTE || route === MULTISIG_ROT_ROUTE || route === MULTISIG_IXN_ROUTE;
 }
-function isVdrRoute(route) {
+export function isVdrRoute(route) {
     return route === MULTISIG_VCP_ROUTE || route === MULTISIG_ISS_ROUTE || route === MULTISIG_REV_ROUTE;
 }
 function requireText(value, label) {