keri-ts 0.11.0 → 2.0.0

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

@@ -1,537 +0,0 @@
-/**
- * Multisig proposal and approval workflows.
- *
- * CLI adapters own prompts, output, and argument parsing. This module owns
- * proposal publishing, mailbox polling, KEL/RPY/VDR approval, and delegation
- * completion for command-local multisig operations.
- */
-import { concatBytes, Diger, Ilks, NumberPrimitive, NumDex, Prefixer, Saider, Seqner, SerderACDC, SerderKERI, TraitDex, } from "cesr-ts";
-import { action } from "effection";
-import { ValidationError } from "../core/errors.js";
-import { messagize } from "../core/protocol-serialization.js";
-import { RegistryRecord } from "../core/records.js";
-import { Reger } from "../db/reger.js";
-import { Credentialer, Regery, Registry, serializeCredential } from "../vdr/credentialing.js";
-import { Tevery } from "../vdr/eventing.js";
-import { processMailboxTurn, processRuntimeUntil } from "./agent-runtime.js";
-import { resolveDelegationCommunicationHab } from "./delegating.js";
-import { endpointRoleAccepted, groupEndorseReply, groupEventKeys, groupSigningMembers, localGroupMember, signLocalGroupEvent, } from "./endpoint-roleing.js";
-import { findLocalGroupMember as findLocalMember, uniqueMembers } from "./group-members.js";
-import { MULTISIG_ICP_ROUTE, MULTISIG_ISS_ROUTE, MULTISIG_IXN_ROUTE, MULTISIG_ROT_ROUTE, MULTISIG_RPY_ROUTE, MULTISIG_VCP_ROUTE, multisigPathedAttachment, } from "./grouping.js";
-import { queryTransportSink } from "./runtime-deliveries.js";
-import { Verifier } from "./verifying.js";
-const MULTISIG_TOPIC = "multisig";
-/** Publish one KEL-style group proposal to remote members. */
-export function* publishProposal(runtime, member, recipients, route, label, payload, embeddedMessage) {
-    return yield* publishProposalEmbeds(runtime, member, recipients, route, payload, { [label]: embeddedMessage });
-}
-/** Publish one multisig proposal with explicit embedded attachments. */
-export function* publishProposalEmbeds(runtime, member, recipients, route, payload, embeds) {
-    const deliveries = [];
-    for (const recipient of uniqueMembers(recipients)) {
-        if (recipient === member.pre || runtime.hby.habs.has(recipient)) {
-            continue;
-        }
-        const result = yield* runtime.poster.sendExchange(member, {
-            recipient,
-            route,
-            payload,
-            embeds,
-            topic: MULTISIG_TOPIC,
-        });
-        deliveries.push(...result.deliveries, ...result.queued);
-    }
-    return deliveries;
-}
-/** Poll until a specific group KEL event is accepted or attempts expire. */
-export function* waitForGroupAcceptance(hby, runtime, serder, options) {
-    if (eventAccepted(hby, serder)) {
-        return true;
-    }
-    for (let turn = 0; turn < options.pollTurns; turn++) {
-        yield* processOnePendingApproval(hby, runtime, options);
-        if (eventAccepted(hby, serder)) {
-            return true;
-        }
-        yield* processMailboxTurn(runtime, { budgetMs: options.pollBudgetMs });
-        yield* runtime.reactor.processEscrowsOnce();
-        yield* sleep(250);
-    }
-    return eventAccepted(hby, serder);
-}
-/** Poll for and approve one pending multisig notification. */
-export function* waitForOneApproval(hby, runtime, options) {
-    for (let turn = 0; turn < options.pollTurns; turn++) {
-        const result = yield* processOnePendingApproval(hby, runtime, options);
-        if (result) {
-            return result;
-        }
-        yield* processMailboxTurn(runtime, { budgetMs: options.pollBudgetMs });
-        yield* runtime.reactor.processEscrowsOnce();
-        yield* sleep(250);
-    }
-    return null;
-}
-/** Wait for a locally authored group event to complete through stored approvals. */
-export 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: [],
-    };
-}
-/** Poll for endpoint-role reply state after a group RPY proposal. */
-export function* waitForReplyAcceptance(hby, runtime, groupPre, role, eid, options) {
-    if (endpointRoleAccepted(hby, groupPre, role, eid)) {
-        return true;
-    }
-    for (let turn = 0; turn < options.pollTurns; turn++) {
-        yield* processOnePendingApproval(hby, runtime, options);
-        if (endpointRoleAccepted(hby, groupPre, role, eid)) {
-            return true;
-        }
-        yield* processMailboxTurn(runtime, { budgetMs: options.pollBudgetMs });
-        yield* runtime.reactor.processEscrowsOnce();
-        yield* sleep(250);
-    }
-    return endpointRoleAccepted(hby, groupPre, role, eid);
-}
-/** Complete the delegation workflow for an accepted delegated group event. */
-export 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 sink = queryTransportSink(runtime, hby, communicationHab);
-    yield* processRuntimeUntil(runtime, () => runtime.delegating.complete(pre, kever.sn), { hab: communicationHab, sink, maxTurns: 512, pollMailbox: true });
-    return runtime.delegating.workflowStatus(pre, kever.sner.numh).phase;
-}
-/** True when a KEL event is accepted locally. */
-export function eventAccepted(hby, serder) {
-    const pre = serder.pre;
-    const said = serder.said;
-    const sn = serder.sn;
-    if (!pre || !said || sn === null) {
-        return false;
-    }
-    return hby.db.kels.getLast(pre, sn) === said;
-}
-export function routeForKelEvent(serder) {
-    switch (serder.ilk) {
-        case Ilks.icp:
-        case Ilks.dip:
-            return MULTISIG_ICP_ROUTE;
-        case Ilks.rot:
-        case Ilks.drt:
-            return MULTISIG_ROT_ROUTE;
-        case Ilks.ixn:
-            return MULTISIG_IXN_ROUTE;
-        default:
-            return null;
-    }
-}
-function* processOnePendingApproval(hby, runtime, options) {
-    const notifier = runtime.notifier;
-    if (!notifier) {
-        throw new ValidationError("Multisig join requires notification storage.");
-    }
-    const notices = notifier.list(0, 100);
-    for (const note of notices) {
-        const route = note.attrs.r;
-        const said = note.attrs.d;
-        if (typeof route !== "string" || typeof said !== "string") {
-            continue;
-        }
-        if (options.said && options.said !== said) {
-            continue;
-        }
-        if (route !== MULTISIG_ICP_ROUTE
-            && route !== MULTISIG_ROT_ROUTE
-            && route !== MULTISIG_IXN_ROUTE
-            && route !== MULTISIG_VCP_ROUTE
-            && route !== MULTISIG_ISS_ROUTE
-            && route !== MULTISIG_RPY_ROUTE) {
-            continue;
-        }
-        const exn = hby.db.exns.get([said]);
-        if (!exn?.ked) {
-            continue;
-        }
-        const result = isKelRoute(route)
-            ? yield* approveKelProposal(hby, runtime, exn, route, options)
-            : isVdrRoute(route)
-                ? yield* approveVdrProposal(hby, runtime, exn, route, options)
-                : yield* approveRpyProposal(hby, runtime, exn, route, options);
-        if (result) {
-            notifier.remove(note.rid);
-            return result;
-        }
-    }
-    return null;
-}
-function* approveRpyProposal(hby, runtime, exn, route, options) {
-    const wrapperSaid = exn.said;
-    if (!wrapperSaid) {
-        return null;
-    }
-    const payload = payloadSection(exn.ked ?? {});
-    const groupPre = requireText(stringField(payload, "gid") || undefined, "Group prefix");
-    const groupHab = hby.habs.get(groupPre);
-    if (!groupHab) {
-        throw new ValidationError(`Group ${groupPre} must be joined before approving ${route}.`);
-    }
-    const member = localGroupMember(hby, groupPre);
-    const embeddedSad = embeddedSection(exn.ked ?? {})?.rpy;
-    if (!isRecord(embeddedSad)) {
-        return null;
-    }
-    const rpySerder = new SerderKERI({ sad: embeddedSad });
-    const embeddedSaid = rpySerder.said ?? "";
-    if (!options.callbacks.approveProposal({ route, group: groupPre, embedded: embeddedSaid || "<unknown>" })) {
-        return null;
-    }
-    const peerAttachment = multisigPathedAttachment(hby, wrapperSaid, "rpy");
-    yield* runtime.reactor.processBytes(concatBytes(rpySerder.raw, peerAttachment), { local: true });
-    const localRpy = groupEndorseReply(hby, groupPre, rpySerder);
-    yield* runtime.reactor.processBytes(localRpy, { local: true });
-    yield* runtime.reactor.processEscrowsOnce();
-    const attrs = rpyAttrs(rpySerder);
-    const deliveries = yield* publishProposalEmbeds(runtime, member, groupSigningMembers(hby, groupPre), route, payload, { rpy: localRpy });
-    const accepted = endpointRoleAccepted(hby, attrs.cid, attrs.role, attrs.eid);
-    return { route, said: wrapperSaid, embedded: embeddedSaid, group: groupPre, accepted, deliveries };
-}
-function* approveKelProposal(hby, runtime, exn, route, options) {
-    const wrapperSaid = exn.said;
-    if (!wrapperSaid) {
-        return null;
-    }
-    const payload = payloadSection(exn.ked ?? {});
-    const label = route === MULTISIG_ICP_ROUTE ? "icp" : route === MULTISIG_ROT_ROUTE ? "rot" : "ixn";
-    const embeddedSad = embeddedSection(exn.ked ?? {})?.[label];
-    if (!isRecord(embeddedSad)) {
-        return null;
-    }
-    const serder = new SerderKERI({ sad: embeddedSad });
-    const embeddedSaid = serder.said;
-    const groupPre = groupPrefixFromProposal(route, payload, serder);
-    const members = proposalMembers(route, payload);
-    const member = route === MULTISIG_IXN_ROUTE ? localGroupMember(hby, groupPre) : findLocalMember(hby, members);
-    if (!member) {
-        throw new ValidationError(`No local member found for multisig proposal ${wrapperSaid}.`);
-    }
-    if (!options.callbacks.approveProposal({ route, group: groupPre, embedded: embeddedSaid ?? "<unknown>" })) {
-        return null;
-    }
-    if (route === MULTISIG_ICP_ROUTE || (route === MULTISIG_ROT_ROUTE && !hby.habs.has(groupPre))) {
-        const smids = stringArrayField(payload, "smids");
-        const rmids = stringArrayField(payload, "rmids");
-        const alias = options.callbacks.chooseGroupAlias(groupPre);
-        hby.joinGroupHab(groupPre, alias, member, smids, rmids.length > 0 ? rmids : smids);
-    }
-    const keys = groupEventKeys(hby, groupPre, serder);
-    const smids = route === MULTISIG_IXN_ROUTE ? stringArrayField(payload, "smids") : proposalSigningMembers(payload);
-    const sigers = signLocalGroupEvent(hby, serder, smids, keys);
-    // Keep the attachment set open until the peer signatures are appended.
-    const localMessage = messagize(serder, { sigers, pipelined: false });
-    const peerAttachment = multisigPathedAttachment(hby, wrapperSaid, label);
-    yield* runtime.reactor.processBytes(concatBytes(localMessage, peerAttachment), { local: true });
-    yield* runtime.reactor.processEscrowsOnce();
-    const deliveries = yield* publishProposal(runtime, member, members, route, label, payload, localMessage);
-    const accepted = eventAccepted(hby, serder);
-    if (accepted && (route === MULTISIG_ICP_ROUTE || route === MULTISIG_ROT_ROUTE)) {
-        const rmids = stringArrayField(payload, "rmids");
-        hby.commitGroupHabMembers(groupPre, smids, rmids.length > 0 ? rmids : smids);
-    }
-    return { route, said: wrapperSaid, embedded: embeddedSaid ?? "", group: groupPre, accepted, deliveries };
-}
-function* approveVdrProposal(hby, runtime, exn, route, options) {
-    const wrapperSaid = exn.said;
-    if (!wrapperSaid) {
-        return null;
-    }
-    const payload = payloadSection(exn.ked ?? {});
-    const groupPre = requireText(stringField(payload, "gid") || undefined, "Group prefix");
-    const groupHab = hby.habs.get(groupPre);
-    if (!groupHab) {
-        throw new ValidationError(`Group ${groupPre} must be joined before approving ${route}.`);
-    }
-    const member = localGroupMember(hby, groupPre);
-    const embed = embeddedSection(exn.ked ?? {});
-    const label = route === MULTISIG_VCP_ROUTE ? "vcp" : "iss";
-    const embeddedSad = embed?.[label];
-    const anchorSad = embed?.anc;
-    if (!isRecord(embeddedSad) || !isRecord(anchorSad)) {
-        return null;
-    }
-    const embeddedSerder = new SerderKERI({ sad: embeddedSad });
-    const anchorSerder = new SerderKERI({ sad: anchorSad });
-    const embeddedSaid = embeddedSerder.said ?? "";
-    if (!options.callbacks.approveProposal({ route, group: groupPre, embedded: embeddedSaid || "<unknown>" })) {
-        return null;
-    }
-    const smids = groupSigningMembers(hby, groupPre);
-    const keys = groupEventKeys(hby, groupPre, anchorSerder);
-    const sigers = signLocalGroupEvent(hby, anchorSerder, smids, keys);
-    // Keep the attachment set open until the peer signatures are appended.
-    const localAnchor = messagize(anchorSerder, { sigers, pipelined: false });
-    const peerAnchorAttachment = multisigPathedAttachment(hby, wrapperSaid, "anc");
-    yield* runtime.reactor.processBytes(concatBytes(localAnchor, peerAnchorAttachment), { local: true });
-    yield* runtime.reactor.processEscrowsOnce();
-    let accepted = false;
-    let embeds;
-    if (route === MULTISIG_VCP_ROUTE) {
-        accepted = approveRegistryIncept(runtime, groupHab, embeddedSerder, anchorSerder, options);
-        embeds = { vcp: embeddedSerder.raw, anc: localAnchor };
-    }
-    else {
-        const acdcSad = embed?.acdc;
-        if (!isRecord(acdcSad)) {
-            return null;
-        }
-        const creder = new SerderACDC({ sad: acdcSad });
-        accepted = approveCredentialIssue(runtime, hby, creder, embeddedSerder, anchorSerder);
-        const seal = telCredentialSeal(embeddedSerder);
-        embeds = {
-            acdc: serializeCredential(creder, seal.prefixer, seal.seqner, seal.saider),
-            iss: embeddedSerder.raw,
-            anc: localAnchor,
-        };
-    }
-    const deliveries = yield* publishProposalEmbeds(runtime, member, smids, route, payload, embeds);
-    return { route, said: wrapperSaid, embedded: embeddedSaid, group: groupPre, accepted, deliveries };
-}
-function groupPrefixFromProposal(route, payload, serder) {
-    if (route === MULTISIG_ICP_ROUTE) {
-        return requireText(serder.pre ?? undefined, "Group prefix");
-    }
-    return requireText(stringField(payload, "gid") || serder.pre || undefined, "Group prefix");
-}
-function proposalMembers(route, payload) {
-    if (route === MULTISIG_IXN_ROUTE) {
-        return stringArrayField(payload, "smids");
-    }
-    return uniqueMembers([...stringArrayField(payload, "smids"), ...stringArrayField(payload, "rmids")]);
-}
-function proposalSigningMembers(payload) {
-    return stringArrayField(payload, "smids");
-}
-function approveRegistryIncept(runtime, groupHab, vserder, anchorSerder, options) {
-    const seal = sourceSeal(anchorSerder);
-    requireTevery(runtime).processEvent({ serder: vserder, seqner: seal.seqner, saider: seal.saider });
-    requireRegery(runtime).processEscrows();
-    const regk = requireSerderPrefix(vserder, "registry inception");
-    const registryName = options.callbacks.chooseRegistryName(regk);
-    const cnfg = stringArrayField(vserder.ked ?? {}, "c");
-    registerRegistry(requireRegery(runtime), registryName, groupHab, regk, {
-        noBackers: cnfg.includes(TraitDex.NoBackers),
-        estOnly: cnfg.includes(TraitDex.EstOnly),
-    });
-    const eventSaid = requireSerderSaid(vserder, "registry inception");
-    if (telAccepted(runtime, regk, 0, eventSaid)) {
-        markTelComplete(runtime, regk, 0, eventSaid);
-    }
-    return telAccepted(runtime, regk, 0, eventSaid);
-}
-function approveCredentialIssue(runtime, hby, creder, iserder, anchorSerder) {
-    const seal = sourceSeal(anchorSerder);
-    requireTevery(runtime).processEvent({ serder: iserder, seqner: seal.seqner, saider: seal.saider });
-    requireRegery(runtime).processEscrows();
-    const reger = requireReger(runtime);
-    const vry = requireVerifier(runtime);
-    const credentialer = new Credentialer(hby, { reger, vry });
-    credentialer.validate(creder);
-    const credentialSeal = telCredentialSeal(iserder);
-    const verifierDecision = vry.processCredential({
-        creder,
-        prefixer: credentialSeal.prefixer,
-        seqner: credentialSeal.seqner,
-        saider: credentialSeal.saider,
-    });
-    if (verifierDecision.kind === "accept") {
-        reger.ccrd.pin(requireCredentialSaid(creder), creder);
-    }
-    vry.processEscrows();
-    const telPre = requireSerderPrefix(iserder, "credential issue");
-    const eventSaid = requireSerderSaid(iserder, "credential issue");
-    const sn = iserder.sn ?? 0;
-    if (telAccepted(runtime, telPre, sn, eventSaid)) {
-        markTelComplete(runtime, requireCredentialSaid(creder), sn, eventSaid);
-    }
-    return credentialer.complete(requireCredentialSaid(creder))
-        || reger.saved.get([requireCredentialSaid(creder)]) !== null;
-}
-function registerRegistry(rgy, name, hab, regk, options) {
-    rgy.reger.registries.add(regk);
-    rgy.reger.regs.pin(name, new RegistryRecord({ registryKey: regk, prefix: hab.pre }));
-    if (!rgy.registries.has(name)) {
-        rgy.registries.set(name, new Registry({
-            name,
-            hab,
-            reger: rgy.reger,
-            tvy: rgy.tvy,
-            cues: rgy.cues,
-            regk,
-            noBackers: options.noBackers,
-            estOnly: options.estOnly,
-        }));
-    }
-}
-function sourceSeal(serder) {
-    return { seqner: ordinal(serder.sn ?? 0), saider: new Diger({ qb64: requireSerderSaid(serder, "anchor event") }) };
-}
-function telCredentialSeal(serder) {
-    return {
-        prefixer: new Prefixer({ qb64: requireSerderPrefix(serder, "credential TEL event") }),
-        seqner: ordinal(serder.sn ?? 0),
-        saider: new Diger({ qb64: requireSerderSaid(serder, "credential TEL event") }),
-    };
-}
-function ordinal(num) {
-    const raw = new Uint8Array(16);
-    let value = BigInt(num);
-    for (let i = raw.length - 1; i >= 0; i--) {
-        raw[i] = Number(value & 0xffn);
-        value >>= 8n;
-    }
-    return new NumberPrimitive({ code: NumDex.Huge, raw });
-}
-function seqner(num) {
-    const raw = new Uint8Array(16);
-    let value = BigInt(num);
-    for (let i = raw.length - 1; i >= 0; i--) {
-        raw[i] = Number(value & 0xffn);
-        value >>= 8n;
-    }
-    return new Seqner({ code: NumDex.Huge, raw });
-}
-function requireSerderPrefix(serder, label) {
-    if (!serder.pre) {
-        throw new ValidationError(`${label} is missing prefix.`);
-    }
-    return serder.pre;
-}
-function requireSerderSaid(serder, label) {
-    if (!serder.said) {
-        throw new ValidationError(`${label} is missing SAID.`);
-    }
-    return serder.said;
-}
-function requireCredentialSaid(creder) {
-    if (!creder.said) {
-        throw new ValidationError("Credential is missing SAID.");
-    }
-    return creder.said;
-}
-function telAccepted(runtime, pre, sn, eventSaid) {
-    return requireReger(runtime).tels.getOn(pre, sn)?.qb64 === eventSaid;
-}
-function markTelComplete(runtime, pre, sn, eventSaid) {
-    requireReger(runtime).ctel.pin([pre, seqner(sn).qb64], new Saider({ qb64: eventSaid }));
-}
-function requireReger(runtime) {
-    if (!(runtime.vdr.reger instanceof Reger)) {
-        throw new ValidationError("VDR runtime did not open Reger.");
-    }
-    return runtime.vdr.reger;
-}
-function requireRegery(runtime) {
-    if (!(runtime.vdr.rgy instanceof Regery)) {
-        throw new ValidationError("VDR runtime did not open Regery.");
-    }
-    return runtime.vdr.rgy;
-}
-function requireTevery(runtime) {
-    if (!(runtime.vdr.tvy instanceof Tevery)) {
-        throw new ValidationError("VDR runtime did not open Tevery.");
-    }
-    return runtime.vdr.tvy;
-}
-function requireVerifier(runtime) {
-    if (!(runtime.vdr.vry instanceof Verifier)) {
-        throw new ValidationError("VDR runtime did not open Verifier.");
-    }
-    return runtime.vdr.vry;
-}
-function rpyAttrs(serder) {
-    const attrs = serder.ked?.a;
-    const cid = typeof attrs?.cid === "string" ? attrs.cid : "";
-    const role = typeof attrs?.role === "string" ? attrs.role : "";
-    const eid = typeof attrs?.eid === "string" ? attrs.eid : "";
-    if (!cid || !role || !eid) {
-        throw new ValidationError("Multisig reply is missing cid, role, or eid.");
-    }
-    return { cid, role, eid };
-}
-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 payloadSection(ked) {
-    return isRecord(ked.a) ? ked.a : {};
-}
-function embeddedSection(ked) {
-    if (isRecord(ked.e)) {
-        return ked.e;
-    }
-    const attrs = payloadSection(ked);
-    return isRecord(attrs.e) ? attrs.e : null;
-}
-function stringArrayField(record, field) {
-    const value = record[field];
-    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
-}
-function stringField(record, field) {
-    const value = record[field];
-    return typeof value === "string" ? value : "";
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isKelRoute(route) {
-    return route === MULTISIG_ICP_ROUTE || route === MULTISIG_ROT_ROUTE || route === MULTISIG_IXN_ROUTE;
-}
-function isVdrRoute(route) {
-    return route === MULTISIG_VCP_ROUTE || route === MULTISIG_ISS_ROUTE;
-}
-function requireText(value, label) {
-    if (!value) {
-        throw new ValidationError(`${label} is required and cannot be empty.`);
-    }
-    return value;
-}
-function* sleep(ms) {
-    yield* action((resolve) => {
-        const id = setTimeout(resolve, ms);
-        return () => clearTimeout(id);
-    });
-}