keri-ts 2.1.0 → 2.2.0

package/esm/keri/npm/src/app/ipex/group-ipex.js

@@ -0,0 +1,327 @@
+/**
+ * Runtime-owned operations for a local group's v2 IPEX messages (first user: a group holder's Admit).
+ *
+ * A group-authored IPEX message completes only when enough members have contributed a signature, and each member's
+ * signature is that member's consent. The runtime owns the rest. This module follows the workflow contract
+ * (`app/runtime/workflow-contract.ts`):
+ *
+ * - {@link proposeGroupAdmit} / {@link proposeGroupIpex} (the proposer) and {@link approveGroupIpex} (every other
+ *   member) are the explicit consents. Each signs or reuses this member's contribution, accepts it locally, records
+ *   a live operation and returns without waiting on anyone. {@link groupIpexProposals} lists the stored proposals a
+ *   member may approve.
+ * - `processOnce`, driven by the runtime's owner loop, publishes this member's wrapper to the other members (retrying
+ *   a member that is briefly offline), collects the other members' stored contributions, and, once the message is
+ *   accepted, lets the elected lead send the completed message to its recipient. It signs nothing beyond the
+ *   contribution that the consent recorded.
+ * - {@link groupIpexStatus} is a pure read and {@link waitForGroupIpex} only observes.
+ *
+ * Status is derived from the protocol stores: an accepted message reads `done`; a stored proposal without a live
+ * operation reads `awaitingConsent` (a member that reloaded consents again with the same call and reuses its
+ * recorded signature). Lost on reload, by design: whether the lead had already delivered the completed message,
+ * the `failed` and `abandoned` reasons, and the publication results. The runtime never writes wallet inventory; the
+ * embedder reacts to the pushed `{kind: "ipex", id: <message>}` change.
+ */
+import { concatBytes, Counter, Vrsn_2_0 } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
+import { registryEventStatus, settleRegistryEvent } from "../credentials/registry-settling.js";
+import { isLocalGroupHab } from "../multisig/group-members.js";
+import { MULTISIG_EXN_ROUTE } from "../multisig/grouping.js";
+import { RetryBackoff } from "../runtime/retry-backoff.js";
+import { observeUntil } from "../runtime/workflow-contract.js";
+import { IpexAdmitter } from "./ipex-admitting.js";
+import { approveMultisigIpexLocally, approveStoredMultisigIpexWrappers, findStoredMultisigIpex, groupIpexApproved, prepareAcdcV2GroupIpex, publishGroupIpexProposal, publishInitialGroupIpex, requireAcdcV2GroupUse, sendCompletedGroupIpex, storedMultisigIpexBody, } from "./ipex-grouping.js";
+/** Milliseconds between collections of the other members' stored contributions. */
+export const GROUP_IPEX_COLLECT_MS = 250;
+/** How long delivery failures may last before an operation ends `failed`; a group IPEX message has no deadline. */
+export const GROUP_IPEX_RETRY_BOUND_MS = 600_000;
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The live table of group IPEX operations and its driver; one per host runtime. */
+export class GroupIpexOperations {
+    constructor(deps) {
+        Object.defineProperty(this, "deps", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: deps
+        });
+        Object.defineProperty(this, "live", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "ended", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** What accepted operations published and delivered in this process; not durable. */
+        Object.defineProperty(this, "outcomes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /** Whether a pass has work. */
+    active() {
+        return this.live.size > 0;
+    }
+    /** Advance every live operation by one pass. */
+    *processOnce() {
+        for (const op of [...this.live.values()]) {
+            if (op.busy || !this.live.has(op.said))
+                continue;
+            op.busy = true;
+            try {
+                yield* this.step(op);
+            }
+            catch (error) {
+                this.end(op, "failed", message(error));
+            }
+            finally {
+                op.busy = false;
+            }
+        }
+    }
+    /** End a live operation and tell the sink. */
+    end(op, state, reason) {
+        this.live.delete(op.said);
+        this.ended.set(op.said, { state, reason });
+        this.deps.changes?.push({ kind: "ipex", id: op.said });
+    }
+    /** Record an operation the user consented to. */
+    begin(said, group, genus, outbound, deliver = true, prerequisite = null) {
+        this.ended.delete(said);
+        this.live.set(said, {
+            said,
+            group,
+            genus,
+            phase: prerequisite ? "awaitingRegistryUpdate" : outbound ? "publishing" : "awaitingMembers",
+            outbound,
+            prerequisite,
+            publication: null,
+            delivered: !deliver,
+            deliveries: [],
+            retry: new RetryBackoff(),
+            nextCollect: 0,
+            busy: false,
+        });
+        this.deps.changes?.push({ kind: "ipex", id: said });
+        return { said };
+    }
+    setPhase(op, phase) {
+        if (op.phase === phase)
+            return;
+        op.phase = phase;
+        this.deps.changes?.push({ kind: "ipex", id: op.said });
+    }
+    /** Run a delivery; a failure keeps the work for a later pass until failures have lasted the bound. */
+    *attempt(op, send) {
+        const now = this.deps.clock.now();
+        if (!op.retry.due(now))
+            return false;
+        try {
+            yield* send();
+            op.retry.succeeded();
+            return true;
+        }
+        catch (error) {
+            op.retry.failed(now, error);
+            if (op.retry.exhausted(now, GROUP_IPEX_RETRY_BOUND_MS)) {
+                throw new ValidationError(`Delivery kept failing: ${message(error)}`);
+            }
+            return false;
+        }
+    }
+    *step(op) {
+        const { hby, protocol, postman, exc, rgy, clock } = this.deps;
+        if (op.prerequisite) {
+            const read = { db: hby.db, store: rgy.store, protocol };
+            const { anchor, proceed } = op.prerequisite;
+            if (registryEventStatus(read, anchor).state !== "accepted") {
+                if ((yield* settleRegistryEvent(read, anchor)).state !== "accepted")
+                    return;
+            }
+            op.outbound = { kind: "initial", wire: yield* proceed() };
+            op.prerequisite = null;
+            this.setPhase(op, "publishing");
+        }
+        if (op.outbound) {
+            const { kind, wire } = op.outbound;
+            const sent = yield* this.attempt(op, function* () {
+                op.publication = kind === "initial"
+                    ? yield* publishInitialGroupIpex(hby, protocol, postman, op.group, wire, op.genus)
+                    : yield* publishGroupIpexProposal(hby, protocol, postman, op.group, wire, op.genus);
+            });
+            if (!sent)
+                return;
+            op.outbound = null;
+            this.setPhase(op, "awaitingMembers");
+        }
+        if (!exc.complete(op.said) && clock.now() >= op.nextCollect) {
+            op.nextCollect = clock.now() + GROUP_IPEX_COLLECT_MS;
+            // This operation exists only because this member consented, so collecting reuses its recorded contribution.
+            yield* approveStoredMultisigIpexWrappers(hby, protocol, op.said, null);
+        }
+        if (!exc.complete(op.said))
+            return;
+        const embedded = hby.db.exns.get([op.said]);
+        requireAcdcV2GroupUse(hby, protocol, embedded);
+        if (!op.delivered) {
+            if (exc.lead(op.group, op.said)) {
+                this.setPhase(op, "delivering");
+                const sent = yield* this.attempt(op, function* () {
+                    op.deliveries = yield* sendCompletedGroupIpex(hby, postman, null, op.group, embedded, op.genus, rgy.store, exc);
+                });
+                if (!sent)
+                    return;
+            }
+            op.delivered = true;
+        }
+        this.live.delete(op.said);
+        this.outcomes.set(op.said, {
+            messages: op.publication?.messages ?? [],
+            deliveries: op.publication?.deliveries ?? [],
+            sent: op.deliveries,
+        });
+        this.deps.changes?.push({ kind: "ipex", id: op.said });
+    }
+}
+/**
+ * The proposer's consent to a group-authored v2 IPEX message: signs this member's contribution to the exact
+ * `exn` body, accepts it locally and records the operation. Publishing the wrapper to the other members is
+ * `processOnce`.
+ *
+ * @throws ValidationError for a body the group did not author, a non-group identifier, a message awaiting
+ * authenticating dependencies, or one already begun.
+ */
+export function* proposeGroupIpex(ops, { hab, exn, nests = new Uint8Array(), gvrsn = Vrsn_2_0, deliver = true }) {
+    const { hby, protocol } = ops.deps;
+    if (!isLocalGroupHab(hby, hab))
+        throw new ValidationError("Group IPEX requires a local group identifier");
+    if (exn.pre !== hab.pre || !exn.said)
+        throw new ValidationError("The IPEX message must be authored by the group");
+    if (ops.live.has(exn.said))
+        throw new ValidationError("A group IPEX message was already begun for this SAID");
+    const candidate = concatBytes(Counter.makeGVC(gvrsn), exn.raw, Counter.enclose({ qb64: nests, version: gvrsn }));
+    const own = yield* prepareAcdcV2GroupIpex(hby, protocol, hab, candidate);
+    if (!own)
+        throw new ValidationError("ACDC v2 group disclosure awaits authenticating dependencies.");
+    return ops.begin(exn.said, hab, gvrsn, { kind: "initial", wire: own }, deliver);
+}
+/**
+ * The proposer's consent to a group-authored message that waits for a registry update, as a Grant carrying a
+ * presentation proof does: the caller has proposed the update (this member's contribution is its approval) and
+ * passes the anchor to wait for. The owner signs the message's contribution, through `prerequisite.proceed`, once
+ * the group has accepted the update, under this same consent. Returns after local commit.
+ */
+export function proposeGroupIpexAfter(ops, { hab, exn, gvrsn = Vrsn_2_0, deliver = true, prerequisite }) {
+    if (!isLocalGroupHab(ops.deps.hby, hab))
+        throw new ValidationError("Group IPEX requires a local group identifier");
+    if (exn.pre !== hab.pre || !exn.said)
+        throw new ValidationError("The IPEX message must be authored by the group");
+    if (ops.live.has(exn.said))
+        throw new ValidationError("A group IPEX message was already begun for this SAID");
+    return ops.begin(exn.said, hab, gvrsn, null, deliver, prerequisite);
+}
+/**
+ * A group holder's consent to admit an accepted Grant: freezes the Admit body (explicit consent, exact prior
+ * authentication and current root truth), then proposes it as {@link proposeGroupIpex} does. The other members list
+ * the proposal and approve it; nothing here records inventory.
+ */
+export function* proposeGroupAdmit(ops, { hab, grant, message = "", gvrsn = Vrsn_2_0, deliver }) {
+    const { hby, rgy, exc } = ops.deps;
+    if (!isLocalGroupHab(hby, hab))
+        throw new ValidationError("Group IPEX requires a local group identifier");
+    const admit = yield* new IpexAdmitter(hby, rgy.store, exc).prepareAdmitBody(grant, hab.pre, {
+        consent: true,
+        message,
+        gvrsn,
+    });
+    return { ...(yield* proposeGroupIpex(ops, { hab, exn: admit, gvrsn, deliver })), grant };
+}
+/** Stored v2 IPEX proposals of `hab` (or of every local group) that were proposed by a member, newest unordered. */
+export function groupIpexProposals(ops, hab) {
+    const { hby, exc } = ops.deps, found = [];
+    for (const [, wrapper] of hby.db.exns.getTopItemIter()) {
+        if (wrapper.route !== MULTISIG_EXN_ROUTE || wrapper.pvrsn.major !== 2)
+            continue;
+        const embedded = storedMultisigIpexBody(hby.db, wrapper);
+        const group = embedded?.pre;
+        if (!embedded?.route?.startsWith("/ipex/") || !group || (hab && group !== hab.pre)
+            || !hby.habs.get(group) || !isLocalGroupHab(hby, hby.habs.get(group)))
+            continue;
+        if (found.some((item) => item.said === embedded.said))
+            continue;
+        found.push({
+            said: embedded.said,
+            route: embedded.route,
+            group,
+            wrapper: wrapper.said,
+            proposer: wrapper.pre,
+            ...(typeof embedded.sad?.p === "string" && embedded.sad.p ? { prior: embedded.sad.p } : {}),
+            approved: groupIpexApproved(hby, group, embedded),
+            complete: exc.complete(embedded.said),
+        });
+    }
+    return found;
+}
+/**
+ * A member's consent to a stored group IPEX proposal: verifies the exact stored wrapper, signs or reuses this
+ * member's contribution and accepts it locally, and records the operation. Publishing it, collecting the other
+ * members' contributions and, for the lead, delivering the completed message are `processOnce`.
+ *
+ * An accepted message may be approved again: the recorded contribution is reused, and the elected lead delivers the
+ * completed message, which a lead that learned of the acceptance from another member's wrapper has not yet done.
+ *
+ * @throws ValidationError when no v2 proposal is stored for `said`, an operation is already live for it, or this
+ * member still lacks the evidence to approve it.
+ */
+export function* approveGroupIpex(ops, said, { deliver = true } = {}) {
+    const { hby, protocol } = ops.deps;
+    if (ops.live.has(said))
+        throw new ValidationError("A group IPEX message was already begun for this SAID");
+    const wrapper = findStoredMultisigIpex(hby.db, said);
+    if (!wrapper || wrapper.pvrsn.major !== 2)
+        throw new ValidationError("No stored group IPEX proposal for this SAID");
+    const { groupHab, genus, approved } = yield* approveMultisigIpexLocally(hby, protocol, null, wrapper);
+    if (!approved)
+        throw new ValidationError("This member lacks the evidence to approve the proposal yet");
+    return ops.begin(said, groupHab, genus, { kind: "proposal", wire: approved }, deliver);
+}
+/** Local abandon: stop publishing and collecting. Does not undo a recorded contribution or message the peers. */
+export function abandonGroupIpex(ops, said, reason = "Abandoned by the user") {
+    const live = ops.live.get(said);
+    if (live)
+        ops.end(live, "abandoned", reason);
+}
+/**
+ * Pure read of one group IPEX message: what ended in this process, the live table, and otherwise what the stores
+ * prove (see the module doc).
+ *
+ * @throws ValidationError when no stored proposal or accepted message of a local group has this SAID.
+ */
+export function groupIpexStatus(ops, said) {
+    const ended = ops.ended.get(said), live = ops.live.get(said);
+    if (ended)
+        return { state: ended.state, reason: ended.reason };
+    if (live)
+        return { state: "active", phase: live.phase };
+    const { hby, exc } = ops.deps;
+    if (exc.complete(said))
+        return { state: "done", phase: "accepted" };
+    if (!findStoredMultisigIpex(hby.db, said)) {
+        throw new ValidationError("No group IPEX proposal is stored for this SAID");
+    }
+    return { state: "active", phase: "awaitingConsent", needs: "approve" };
+}
+/** Observe until the message is accepted and delivered, or ended, or the budget expires. Starts no worker. */
+export function* waitForGroupIpex(ops, said, { timeoutMs, clock = ops.deps.clock, until = (status) => status.state !== "active" }) {
+    const settled = yield* observeUntil(() => until(groupIpexStatus(ops, said)), { timeoutMs, clock });
+    const status = groupIpexStatus(ops, said);
+    return settled ? { outcome: "settled", status } : { outcome: "timed-out", status, timeoutMs };
+}