keri-ts 2.2.4 → 2.2.6

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

@@ -16,6 +16,9 @@
  * | holder custodian or member    | {@link approveGroupIssuanceExchange}      | consent to DH (contributions follow as they arrive) |
  * | a member that only follows    | {@link followGroupIssuanceProof}          | nothing; verifies the custodian's final proof       |
  *
+ * The follow is not a consent and needs no call: the owner begins it itself (below). The explicit call remains for a
+ * proof supplied as bytes and is idempotent with the automatic follow.
+ *
  * The registry update is a separate consent: the custodian proposes the BUP through `proposeRegistryEvent`
  * (its own contribution is its approval) and every other issuer member approves that proposal with
  * `approveGroupProposal`. Admit is a separate consent as well.
@@ -25,20 +28,30 @@
  * Grant and the proof broadcast to the other members. Root copies are not sent here: the DH completion cue
  * feeds the runtime's `RootReplicator`, which sends exactly one copy per member.
  *
+ * Automatic follow: on its slow sweep of the pending exchange escrow the owner begins the proof-only follow, in either
+ * role, of each pending group Grant inside its deadline that this member has no live, ended or complete operation for
+ * and whose custodian's final proof is stored ({@link storedGroupProof}). The proof exists only after the key exchange
+ * finished, so the follow never takes the place of a member whose signature is still wanted; until the proof or a root
+ * copy is stored the member reads `awaitingExchangeConsent` and consents as usual. A member holding a root copy or the
+ * proof reads `awaitingAnchor` ({@link awaitsGroupProof}) until the follow accepts the Grant.
+ *
  * Reload: nothing about a group operation is durable but the protocol stores. A member that reloads reads
  * `awaitingExchangeConsent` for a pending Grant it holds no root for and consents again with the same call;
  * its signatures are deterministic, so consenting twice produces the same bytes. A custodian that reloaded
- * after retaining its root resumes when the stores allow it ({@link deriveGroupCustody}).
+ * after retaining its root resumes when the stores allow it ({@link deriveGroupCustody}). A follow signs nothing, so
+ * the first sweep after a reload begins it again from the stored proof.
  */
 import { bytesEqual, collectPayload, concatBytes, Counter, framePayload, parseBytes, SerderACDC, SerderKERI, Vrsn_2_0, } from "cesr-ts";
 import { call } from "effection";
 import { RegistryAuthor } from "../../acdc/authoring.js";
 import { RegistryCustody } from "../../acdc/custody.js";
 import { Dhke, grantTransactionId } from "../../acdc/dhking.js";
+import { ThresholdQueryResend } from "../../acdc/query-resend.js";
 import { vet } from "../../acdc/regeventing.js";
 import { RegistryRoot } from "../../acdc/salting.js";
 import { ValidationError } from "../../core/errors.js";
 import { Kever } from "../../core/kel/kever.js";
+import { multiKeyQueryWindow } from "../../core/mailbox/kram-policy.js";
 import { messagize } from "../../core/protocol-serialization.js";
 import { loadNests } from "../../db/exchange/exchange-nests.js";
 import { timestampMicros } from "../../time/mod.js";
@@ -197,29 +210,76 @@ export function deriveGroupCustody(deps, hab, grant) {
     if (!isLocalGroupHab(hby, hab) || !hab.kever)
         return null;
     const member = localGroupMember(hby, hab.pre);
-    const registries = new Set();
-    for (const nest of deps.exc.retainedInput(grant)?.nests ?? []) {
-        const rd = nest.body.ked?.rd;
-        if (typeof rd === "string")
-            registries.add(rd);
-    }
+    const registries = disclosedRegistries(deps.exc, grant);
     if (!registries.size || [...registries].some((registry) => !hab.mgr.hasRegistryRoot(hab.pre, registry))) {
         return null;
     }
     if (receivedRootCopy(hby, hab.pre, member.pre, registries))
         return null;
-    const events = [...hby.db.getKelItemIter(hab.pre)].slice(-GROUP_COORDINATOR_SEARCH);
+    const coordinator = electingCoordinator(hby, hab.pre, member.pre);
+    return coordinator ? { coordinator, custodian: member.pre, lead: true } : null;
+}
+/** The registries a retained Grant discloses credentials of. */
+function disclosedRegistries(exc, grant) {
+    const registries = new Set();
+    for (const nest of exc.retainedInput(grant)?.nests ?? []) {
+        const rd = nest.body.ked?.rd;
+        if (typeof rd === "string")
+            registries.add(rd);
+    }
+    return registries;
+}
+/** The latest of the group's recent accepted events whose threshold evidence elects `member`, or null. */
+function electingCoordinator(hby, group, member) {
+    const events = [...hby.db.getKelItemIter(group)].slice(-GROUP_COORDINATOR_SEARCH);
     for (const [, said] of events.reverse()) {
-        const event = hby.db.getEvtSerder(hab.pre, said);
+        const event = hby.db.getEvtSerder(group, said);
         if (!event || event.sn === null)
             continue;
         const coordinator = { sn: event.sn, said: event.said };
-        if (groupElectedMember(hby, hab.pre, coordinator) === member.pre) {
-            return { coordinator, custodian: member.pre, lead: true };
-        }
+        if (groupElectedMember(hby, group, coordinator) === member)
+            return coordinator;
     }
     return null;
 }
+/**
+ * The election of a final proof the local member of `hab` can follow for `grant` without taking part: the
+ * `/multisig/ipex-proof` wrapper of this exact Grant that another current signing member published, with a recent
+ * accepted group event electing that member as custodian. The custodian publishes the proof only after the key
+ * exchange finished and the registry update was accepted, so once it is stored no member's signature is still wanted
+ * for this issuance. The sender names the custodian exactly, which a root copy cannot (any member holding a root
+ * sends copies). Null when no such proof is stored. A pure read of the stored exchanges.
+ */
+export function storedGroupProof(deps, hab, grant) {
+    const { hby } = deps;
+    if (!isLocalGroupHab(hby, hab) || !hab.kever)
+        return null;
+    const member = localGroupMember(hby, hab.pre).pre, signing = groupSigningMembers(hby, hab.pre);
+    for (const [, parent] of hby.db.exns.getTopItemIter()) {
+        const attrs = parent.sad?.a;
+        if (parent.route !== MULTISIG_IPEX_PROOF_ROUTE || attrs?.gid !== hab.pre || attrs?.grant !== grant
+            || !parent.pre || parent.pre === member || !signing.includes(parent.pre))
+            continue;
+        const coordinator = electingCoordinator(hby, hab.pre, parent.pre);
+        if (coordinator)
+            return { coordinator, custodian: parent.pre, lead: false };
+    }
+    return null;
+}
+/**
+ * Whether the group completed `grant` without the local member of `hab`, so that its runtime follows the final proof
+ * instead of asking it to consent: a `/registry/root` copy of a disclosed registry was sent to it (copies are
+ * authorized only once the registry update is accepted, after the key exchange), or the custodian's final proof is
+ * stored ({@link storedGroupProof}). A pure read of the stores.
+ */
+export function awaitsGroupProof(deps, hab, grant) {
+    const { hby } = deps;
+    if (!isLocalGroupHab(hby, hab) || !hab.kever)
+        return false;
+    const member = localGroupMember(hby, hab.pre).pre, registries = disclosedRegistries(deps.exc, grant);
+    return (registries.size > 0 && receivedRootCopy(hby, hab.pre, member, registries))
+        || !!storedGroupProof(deps, hab, grant);
+}
 /** Whether `member` was sent a `/registry/root` copy of the group's root for any of `registries`. */
 function receivedRootCopy(hby, group, member, registries) {
     for (const [, copy] of hby.db.exns.getTopItemIter()) {
@@ -421,23 +481,51 @@ export function approveGroupIssuanceExchange(ops, said, coordinator) {
     return ops.beginGroup(new GroupIssuance(party, "holder", grant, nodes));
 }
 /**
- * Follow a group issuance that has already been contributed to, only to verify and accept the custodian's final
- * proof: the file-free path of an issuer member that left after contributing and returns for the proof. The group
- * is the Grant's sender. Signs nothing. The proof may already be stored (it arrives by mailbox), or be supplied as
- * bytes.
+ * Follow a group issuance only to verify and accept the custodian's final proof, signing nothing. It serves any
+ * member that does not contribute to the key exchange: an issuer member that left after contributing and returns
+ * for the proof, or a holder member the group completed without, such as one whose signing weight is 0. The group
+ * is the Grant's sender when that is a local group, otherwise its recipient. The proof may already be stored (it
+ * arrives by mailbox), or be supplied as bytes.
+ *
+ * The owner begins the same follow on its own once the custodian's proof is stored ({@link storedGroupProof}), so a
+ * host needs this call only to supply the proof as bytes or to pin the coordinator. It is idempotent with that
+ * follow; see {@link beginGroupProofFollow}.
  *
- * @throws ValidationError for a Grant this runtime's groups did not send, or one already begun.
+ * @throws ValidationError for a Grant that is not pending for a local group, or one begun under a consent.
  */
 export function* followGroupIssuanceProof(ops, said, options = {}) {
-    const { deps } = ops;
-    if (ops.liveOf(said, "issuer") || partyComplete(deps, said, "issuer")) {
+    const { deps } = ops, sent = deps.exc.retainedInput(said)?.serder.pre;
+    const sender = sent ? deps.hby.habs.get(sent) : undefined;
+    const role = sender && isLocalGroupHab(deps.hby, sender) ? "issuer" : "holder";
+    const begun = beginGroupProofFollow(ops, said, role, options.coordinator);
+    // Stored for the follow's next scan, whether it began now or earlier.
+    if (options.proof)
+        yield* deps.reactor.processBytes(options.proof);
+    return begun;
+}
+/**
+ * Begin `role`'s proof-only follow of the pending group Grant `said` under `coordinator` (default the group's latest
+ * establishment event). Signs nothing. Idempotent: when that party's follow is already live, or its side of the Grant
+ * is already complete, returns the Grant and its transaction and begins nothing. The owner's sweep and
+ * {@link followGroupIssuanceProof} both begin follows here.
+ *
+ * @throws ValidationError for a Grant that is not pending for a local group, one whose live operation is a consent,
+ * or a coordinator {@link GroupParty.resolve} refuses.
+ */
+export function beginGroupProofFollow(ops, said, role, coordinator) {
+    const { deps } = ops, live = ops.liveOf(said, role);
+    if (live?.group?.mode === "proofOnly")
+        return { grant: said, xid: live.xid };
+    if (live)
         throw new ValidationError("Issuance was already begun for this Grant");
+    if (partyComplete(deps, said, role)) {
+        const serder = deps.exc.retainedInput(said)?.serder;
+        return { grant: said, xid: serder ? grantTransactionId(serder) : said };
     }
     const { grant, nodes } = pendingGrant(deps, said);
-    const party = GroupParty.resolve(deps, localGroup(deps, grant.pre), options.coordinator);
-    if (options.proof)
-        yield* deps.reactor.processBytes(options.proof);
-    return ops.beginGroup(new GroupIssuance(party, "issuer", grant, nodes, { mode: "proofOnly" }));
+    const group = localGroup(deps, role === "issuer" ? grant.pre : grant.sad.ri);
+    const party = GroupParty.resolve(deps, group, coordinator);
+    return ops.beginGroup(new GroupIssuance(party, role, grant, nodes, { mode: "proofOnly" }));
 }
 /**
  * The custodian's exact public proof of a completed group issuance: the proof support and the
@@ -527,17 +615,12 @@ export class GroupIssuance {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "query", {
+        /** The frozen threshold query and its resend schedule; a group cannot re-date it (`Dhke.requery` refuses groups). */
+        Object.defineProperty(this, "resend", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "nextQuery", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: 0
+            value: new ThresholdQueryResend()
         });
         Object.defineProperty(this, "nextProofScan", {
             enumerable: true,
@@ -565,6 +648,13 @@ export class GroupIssuance {
             writable: true,
             value: void 0
         });
+        /** What the Grant send's proof support carried; absent when this operation did not send it (rebuilt after a restart). */
+        Object.defineProperty(this, "supportMark", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "mode", {
             enumerable: true,
             configurable: true,
@@ -800,7 +890,9 @@ export function* stepGroup(ops, op) {
         const input = deps.exc.retainedInput(grant, { pending: true });
         const frame = parseBytes(messagize(input.serder, { tsgs: input.tsgs, cigars: input.cigars, gvrsn: Vrsn_2_0 }))[0];
         frame.nests = [...input.nests ?? []];
-        const full = concatBytes(ops.discloser.proofSupport(g.nodeBytes, hab), yield* wire(frame));
+        const support = ops.discloser.proofSupport(g.nodeBytes, hab);
+        g.supportMark = ops.discloser.proofSupportMark(g.nodeBytes, hab);
+        const full = concatBytes(support, yield* wire(frame));
         for (const peer of party.others())
             yield* send(peer, full);
         if (issuer) {
@@ -854,13 +946,17 @@ export function* stepGroup(ops, op) {
             yield* broadcast(yield* party.wrap(child, MULTISIG_RPY_ROUTE));
         }
         else if (message.kin === "query")
-            g.query = message.msg;
+            g.resend.set(message.msg);
         else
             yield* send(message.dest, message.msg, "credential");
     }
-    if (g.query && deps.clock.now() >= g.nextQuery && !dh.complete(xid)) {
-        yield* send(g.grant.sad.ri, g.query, "credential");
-        g.nextQuery = deps.clock.now() + (deps.queryResendMs ?? ISSUANCE_QUERY_RESEND_MS);
+    // The unchanged query is resent with backoff while the holder can still accept it; the operation keeps waiting
+    // for the holder past that, to its own deadline.
+    const now = deps.clock.now(), base = deps.queryResendMs ?? ISSUANCE_QUERY_RESEND_MS;
+    if (g.resend.ready(now) && g.resend.fresh(now, multiKeyQueryWindow(deps.hby.db, Dhke.Route))
+        && !dh.complete(xid)) {
+        yield* send(g.grant.sad.ri, g.resend.query, "credential");
+        g.resend.sent(now, base);
     }
     if (!lead || !dh.complete(xid))
         return false;
@@ -894,7 +990,11 @@ export function* stepGroup(ops, op) {
     if (!deps.exc.complete(grant))
         throw new ValidationError("Issued group Grant remains unaccepted");
     const completed = parseBytes(yield* storedBytes(deps.exc, grant))[0];
-    const support = ops.discloser.proofSupport(g.nodeBytes, hab);
+    // The Grant send already carried the support; proving added the anchoring event and the registry update. An
+    // operation without a mark did not send it, so it sends in full.
+    const support = g.supportMark
+        ? ops.discloser.proofSupportSince(g.nodeBytes, hab, g.supportMark)
+        : ops.discloser.proofSupport(g.nodeBytes, hab);
     // KERIpy form: the elected member shares the proof with the other members by mailbox.
     const wrapped = yield* party.wrap(completed, MULTISIG_IPEX_PROOF_ROUTE);
     // Kept locally, so the proof the members received is the one {@link groupIssuanceProof} exports.

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

@@ -88,6 +88,32 @@ export function* storedExchangeWire(retained, gvrsn = Vrsn_2_0) {
     frame.nests = nests;
     return yield* call(() => collectPayload(framePayload(frame)));
 }
+/**
+ * Extend a frozen Grant's exact origin proof with its presented-state opening and the KEL seal of the registry update
+ * that commits to it; the Grant body and its SAID are unchanged. Ordinary intake still authenticates the supplied
+ * presentation evidence. Reads no store and signs nothing.
+ *
+ * @throws ValidationError when the opening does not target this exact Grant's disclosed Issuee in the `presented` state.
+ */
+export function* attachPresentationProof(prepared, opening, source) {
+    const frames = parseBytes(prepared.raw), node = frames[0].body;
+    if (!node.issuee || opening.td.nonce !== prepared.exn.said || opening.ts.label !== "presented") {
+        throw new ValidationError("Presentation proof must target this exact Grant and disclosed Issuee.");
+    }
+    const seal = Counter.enclose({
+        code: "SealSourceTriples",
+        qb64: concatBytes(new Prefixer({ qb64: node.issuee }).qb64b, source.s.qb64b, source.d.qb64b),
+        version: Vrsn_2_0,
+    });
+    const first = concatBytes(node.raw, Counter.enclose({
+        qb64: concatBytes(...frames[0].attachments.map(group => group.raw), publicOpeningAttachment(opening), seal),
+        version: Vrsn_2_0,
+    }));
+    const rest = yield* call(() => Promise.all(frames.slice(1).map(frame => collectPayload(nestedPayload(frame, Vrsn_2_0)))));
+    const raw = concatBytes(Counter.makeGVC(Vrsn_2_0), first, ...rest);
+    const payloads = yield* call(() => Promise.all(parseBytes(raw).map(frame => collectPayload(nestedPayload(frame, Vrsn_2_0)))));
+    return { exn: prepared.exn, raw, nests: concatBytes(...payloads) };
+}
 /** Borrow concrete owners only. No constructor opens a store, starts a worker or loads registry secrets. */
 export class IpexDiscloser {
     constructor(hby, registry, exc, receiptor, custody, views) {
@@ -201,7 +227,65 @@ export class IpexDiscloser {
     }
     /** Carry selected public evidence and root-first delegation ancestry; receiver intake still verifies every approval. */
     proofSupport(raw, hab) {
-        const aids = new Set([hab.pre]), registries = new Set();
+        return this.proofSupportFor(raw, [hab.pre]);
+    }
+    /**
+     * `proofSupport` for explicitly named parties instead of one habitat: the KELs of `parties` and of every identifier
+     * the ACDC frames in `raw` name, each after its delegation ancestry, then the accepted TEL of every registry they
+     * name. Reads accepted state only and signs nothing, so it needs no keys.
+     */
+    proofSupportFor(raw, parties) {
+        const { ordered, registries } = this.supportSelection(raw, parties);
+        const messages = [Counter.makeGVC(Vrsn_2_0)];
+        // Keep first-seen authorizers and exact stored attachments, including superseded history.
+        // clonePreIter skips broken rows; finite disclosure must instead fail if an accepted row cannot be replayed.
+        for (const aid of ordered)
+            messages.push(...this.supportKel(aid, 0));
+        for (const regid of registries)
+            messages.push(this.registry.cloneTel(regid));
+        return concatBytes(...messages);
+    }
+    /**
+     * Record how far `proofSupport(raw, hab)` reaches right now: each KEL's last first-seen ordinal and each
+     * registry's last TEL ordinal. Call it in the same synchronous turn as the send it describes, so the mark is
+     * exactly what that send carried; {@link proofSupportSince} then sends what accepted state has gained.
+     */
+    proofSupportMark(raw, hab) {
+        const { ordered, registries } = this.supportSelection(raw, [hab.pre]);
+        const kels = new Map(), tels = new Map();
+        for (const aid of ordered) {
+            let last = -1;
+            for (const [, fn] of this.hby.db.fels.getAllItemIter(aid))
+                last = fn;
+            kels.set(aid, last);
+        }
+        for (const regid of registries) {
+            let last = -1;
+            for (const [, sn] of this.registry.baser.tels.getAllItemIter(regid))
+                last = sn;
+            tels.set(regid, last);
+        }
+        return { kels, tels };
+    }
+    /**
+     * The part of `proofSupport(raw, hab)` that accepted state gained after `mark` was taken, in the same order and
+     * with the same stored attachments: later first-seen KEL events of each identifier (the anchoring interaction
+     * event of a registry update, say) and later TEL events of each registry. An identifier or registry the mark does
+     * not name (support that grew a new party) is carried whole. A recipient that holds what `mark` describes holds
+     * the same state after this as after a second full `proofSupport`.
+     */
+    proofSupportSince(raw, hab, mark) {
+        const { ordered, registries } = this.supportSelection(raw, [hab.pre]);
+        const messages = [Counter.makeGVC(Vrsn_2_0)];
+        for (const aid of ordered)
+            messages.push(...this.supportKel(aid, (mark.kels.get(aid) ?? -1) + 1));
+        for (const regid of registries)
+            messages.push(this.registry.cloneTel(regid, (mark.tels.get(regid) ?? -1) + 1));
+        return concatBytes(...messages);
+    }
+    /** The identifiers (each after its delegation ancestry) and registries that support for `raw` and `parties` names. */
+    supportSelection(raw, parties) {
+        const aids = new Set(parties), registries = new Set();
         for (const frame of parseBytes(raw)) {
             if (!(frame.body instanceof SerderACDC))
                 continue;
@@ -222,7 +306,6 @@ export class IpexDiscloser {
                     aids.add(seal.i.qb64);
             }
         }
-        const messages = [Counter.makeGVC(Vrsn_2_0)];
         const db = this.hby.db, ordered = new Set();
         // An ancestry claim selects supporting KELs; it does not establish delegation authority.
         for (const aid of aids) {
@@ -241,15 +324,15 @@ export class IpexDiscloser {
             for (const ancestor of ancestors.reverse())
                 ordered.add(ancestor);
         }
-        // Keep first-seen authorizers and exact stored attachments, including superseded history.
-        // clonePreIter skips broken rows; finite disclosure must instead fail if an accepted row cannot be replayed.
-        for (const aid of ordered) {
-            for (const [, fn, said] of db.fels.getAllItemIter(aid))
-                messages.push(db.cloneEvtMsg(aid, fn, said, Vrsn_2_0));
+        return { ordered, registries };
+    }
+    /** Stored first-seen events of `aid` from ordinal `from`, each with its exact stored attachments. */
+    supportKel(aid, from) {
+        const messages = [];
+        for (const [, fn, said] of this.hby.db.fels.getAllItemIter(aid, from)) {
+            messages.push(this.hby.db.cloneEvtMsg(aid, fn, said, Vrsn_2_0));
         }
-        for (const regid of registries)
-            messages.push(this.registry.cloneTel(regid));
-        return concatBytes(...messages);
+        return messages;
     }
     /** Public replay includes actual stored witness receipts; it grants no new consent. */
     kel(hab) {
@@ -399,26 +482,6 @@ export class IpexDiscloser {
         const prior = yield* this.prior(priorSaid);
         return ipexExnBody(sender, `/ipex/${verb}`, [], { message, prior, recipient });
     }
-    /** Extend the frozen Grant's exact origin proof; ordinary intake still authenticates the supplied presentation evidence. */
-    *attachPresentationProof(prepared, opening, source) {
-        const frames = parseBytes(prepared.raw), node = frames[0].body;
-        if (!node.issuee || opening.td.nonce !== prepared.exn.said || opening.ts.label !== "presented") {
-            throw new ValidationError("Presentation proof must target this exact Grant and disclosed Issuee.");
-        }
-        const seal = Counter.enclose({
-            code: "SealSourceTriples",
-            qb64: concatBytes(new Prefixer({ qb64: node.issuee }).qb64b, source.s.qb64b, source.d.qb64b),
-            version: Vrsn_2_0,
-        });
-        const first = concatBytes(node.raw, Counter.enclose({
-            qb64: concatBytes(...frames[0].attachments.map(group => group.raw), publicOpeningAttachment(opening), seal),
-            version: Vrsn_2_0,
-        }));
-        const rest = yield* call(() => Promise.all(frames.slice(1).map(frame => collectPayload(nestedPayload(frame, Vrsn_2_0)))));
-        const raw = concatBytes(Counter.makeGVC(Vrsn_2_0), first, ...rest);
-        const payloads = yield* call(() => Promise.all(parseBytes(raw).map(frame => collectPayload(nestedPayload(frame, Vrsn_2_0)))));
-        return { exn: prepared.exn, raw, nests: concatBytes(...payloads) };
-    }
     /** Select immutable admitted/transferred nests; proof refresh changes attachments only when explicitly requested. */
     *selected(selection, offer = false) {
         if ([selection.said, selection.fromGrant, selection.transferred].filter(value => value !== undefined).length !== 1) {
@@ -540,7 +603,7 @@ export class IpexDiscloser {
             if (reg.store.seqEvent(reg.regk, Number(BigInt(`0x${update.sad.n}`)))?.said !== update.said) {
                 throw new ValidationError("Presentation BUP remains pending authenticated acceptance.");
             }
-            ({ raw, nests } = yield* this.attachPresentationProof({ exn, raw, nests }, proof, seal));
+            ({ raw, nests } = yield* attachPresentationProof({ exn, raw, nests }, proof, seal));
         }
         const source = exn.sad.a.ax?.[0]
             ? yield* anchorExchange(this.hby, this.receiptor, hab, exn, options.auths)

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

@@ -12,7 +12,7 @@ import { call } from "effection";
 import { evaluateChain } from "../../acdc/chaining.js";
 import { resolveAttachmentGvrsn } from "../../core/attachment-countering.js";
 import { TransIdxSigGroup } from "../../core/dispatch.js";
-import { ValidationError } from "../../core/errors.js";
+import { KramRefusedError, ValidationError } from "../../core/errors.js";
 import { verifyExchangeProofs } from "../../core/exchange/exchange-proofing.js";
 import { exchange, serializeMessage } from "../../core/exchange/protocol-exchanging.js";
 import { Kever } from "../../core/kel/kever.js";
@@ -74,7 +74,19 @@ export function requireAcdcV2GroupUse(hby, protocol, embedded) {
         throw new ValidationError("ACDC v2 group graph is unavailable for completed use.");
     }
 }
-/** Approve exactly one ACDC v2 IPEX stream before adding this member's signature; no new acceptance rows are manufactured. */
+/** KRAM refusals after which the message can no longer be accepted; a `replay` is routine, not one of them. */
+const KRAM_EXPIRY_REASONS = new Set(["timestamp", "timeliness", "unknownThread", "lifetime"]);
+/** Whether `decision` is this receiver's KRAM refusing a message for its time, its thread or its lifetime. */
+function isKramExpiry(decision) {
+    return !!decision && decision.kind === "drop" && "reason" in decision && KRAM_EXPIRY_REASONS.has(decision.reason);
+}
+/**
+ * Approve exactly one ACDC v2 IPEX stream before adding this member's signature; no new acceptance rows are manufactured.
+ *
+ * @returns This member's accepted wire, or null while its evidence or dependencies are missing.
+ * @throws KramRefusedError when this member's own KRAM refuses the contribution for its time, thread or exchange
+ * lifetime: the message can no longer be accepted here. A `replay` refusal is routine and is not thrown.
+ */
 export function* prepareAcdcV2GroupIpex(hby, protocol, group, raw) {
     const frames = parseBytes(concatBytes(Counter.makeGVC(Vrsn_2_0), raw));
     const frame = frames[0], embedded = frame?.body;
@@ -136,7 +148,11 @@ export function* prepareAcdcV2GroupIpex(hby, protocol, group, raw) {
     };
     const attachments = yield* call(() => collectPayload(attachmentPayload(approved, { gvrsn: Vrsn_2_0 })));
     const wire = concatBytes(embedded.raw, attachments);
-    yield* new Reactor(protocol).processBytes(wire, { local: true });
+    // Dispatch the frame itself, not its bytes, so this member's own KRAM decision is visible. A refusal here is
+    // not a remote outcome to skip: the contribution was never accepted and nothing else will complete the message.
+    const { decision } = yield* protocol.dispatch(parseBytes(wire)[0], { local: true }, new Reactor(protocol).kvy);
+    if (isKramExpiry(decision))
+        throw new KramRefusedError(embedded.said, decision);
     yield* protocol.processEscrowsOnce();
     return wire;
 }
@@ -457,6 +473,40 @@ export function* approveStoredMultisigIpexWrappers(hby, protocol, embeddedSaid,
         yield* approveIpexChild(hby, protocol, groupHab, child, wrapper, reger);
     }
 }
+/**
+ * The copies this member received of each v2 group IPEX message it has not accepted: per message, the child of each
+ * stored, authenticated `/multisig/exn` wrapper that carries it, with its signatures and nests. A pure read; whether a
+ * message may be taken from its copies is {@link groupIpexFollowable}'s rule.
+ */
+export function unacceptedGroupIpexCopies(hby, exchanger) {
+    const copies = new Map();
+    for (const [, wrapper] of hby.db.exns.getTopItemIter()) {
+        if (wrapper.route !== MULTISIG_EXN_ROUTE || wrapper.pvrsn.major !== 2)
+            continue;
+        const said = storedMultisigIpexBody(hby.db, wrapper)?.said;
+        if (!said || exchanger.complete(said) || !exchanger.verifyAccepted(wrapper.said, MULTISIG_EXN_ROUTE))
+            continue;
+        copies.set(said, [...copies.get(said) ?? [], loadNests(hby.db, wrapper.said)[0]]);
+    }
+    return [...copies.values()];
+}
+/**
+ * Accept a group IPEX message from the copies this member received, adding no signature: dispatch each copy with its
+ * own proofs, then advance escrows so that copies whose signatures only together meet the threshold complete. The
+ * caller has checked {@link groupIpexFollowable}.
+ *
+ * @throws KramRefusedError when this member's own KRAM refuses a copy for its time, thread or exchange lifetime: the
+ * message can no longer be accepted here.
+ */
+export function* acceptGroupIpexCopies(protocol, copies) {
+    const kvy = new Reactor(protocol).kvy;
+    for (const copy of copies) {
+        const { decision } = yield* protocol.dispatch(copy, { local: true }, kvy);
+        if (isKramExpiry(decision))
+            throw new KramRefusedError(copy.body.said, decision);
+    }
+    yield* protocol.processEscrowsOnce();
+}
 /**
  * Return the first incomplete stored `/multisig/exn` wrapping `/ipex/*`.
  *

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

@@ -464,8 +464,13 @@ export class IpexV2Handler {
         }
         return { pending, registries };
     }
-    /** Notify only after Exchanger has durably accepted the parent and its evidence. */
-    handle({ serder }) {
+    /**
+     * Notify only after Exchanger has durably accepted the parent and its evidence. A retained exchange (history a
+     * local import replayed, such as an already admitted Grant and its Admit) is not news: no notice asks anyone to act.
+     */
+    handle({ serder, retained }) {
+        if (retained)
+            return;
         this.notifier?.add({ r: `/exn${serder.route}`, d: serder.said, m: serder.sad.a.m });
     }
     /** Every disclosed own schema vets before presentation and issuer graph reduction. */