keri-ts 2.2.1 → 2.2.3

package/esm/keri/npm/src/app/identity/habbing.js

@@ -30,7 +30,7 @@ import { Keeper, PreSit } from "../../db/keeping.js";
 import { makeNowIso8601 } from "../../time/mod.js";
 import { oobiReplyMessages } from "../bootstrap/oobi-replies.js";
 import { loadStoredReply } from "../delivery/stored-replies.js";
-import { acceptedGroupMembers, latestGroupContribution } from "../multisig/group-members.js";
+import { acceptedGroupMembers, isAcceptedGroupMember, latestGroupContribution } from "../multisig/group-members.js";
 import { branToSaltQb64, encodeHugeNumber, ensureKeeperCryptoReady, Manager, normalizeSaltQb64, saltySigner, } from "./keeping.js";
 /** Reserved alias for the local signatory habitat record. */
 export const SIGNER = "__signatory__";
@@ -1547,6 +1547,10 @@ export class Habery {
      * - this is the TypeScript analogue of `Habery.joinGroupHab()`
      * - it does not fabricate key state; accepted KEL state must still arrive
      *   through `Kevery.processEvent()`
+     * - KERIpy overwrites the recorded member unconditionally. Here a recorded member that is still a
+     *   signing or rotation member of the group's accepted key state is kept (a Habery holding two valid
+     *   members must not switch which one signs), and one that is in neither list is replaced by `mhab`.
+     *   Replacing creates no event and signs nothing; membership itself changes only by rotation.
      */
     joinGroupHab(pre, group, mhab, smids, rmids, ns) {
         if (!pre) {
@@ -1569,18 +1573,54 @@ export class Habery {
             throw new ValidationError(`Group alias ${group} is already bound to ${existingName}.`);
         }
         const existingRecord = this.db.getHab(pre);
-        if (existingRecord?.mid && existingRecord.mid !== mhab.pre) {
-            throw new ValidationError(`Group prefix ${pre} is already joined as ${existingRecord.name}.`);
+        const replacing = !!existingRecord?.mid && existingRecord.mid !== mhab.pre;
+        if (replacing) {
+            // Membership is decided by accepted key state, never by the caller's lists or a proposal.
+            if (!this.db.getKever(pre)) {
+                throw new ValidationError(`Group prefix ${pre} is already joined as ${existingRecord.name}; whether member ${existingRecord.mid} `
+                    + `is still a member cannot be judged until the group has accepted key state.`);
+            }
+            if (isAcceptedGroupMember(this.db, pre, existingRecord.mid)) {
+                throw new ValidationError(`Group prefix ${pre} is already joined as ${existingRecord.name} by member ${existingRecord.mid}, `
+                    + `which is still a member in its accepted key state.`);
+            }
+            if (!isAcceptedGroupMember(this.db, pre, mhab.pre)) {
+                throw new ValidationError(`Local member identifier ${mhab.pre} is not a member in the accepted key state of group ${pre}.`);
+            }
         }
         const hab = this.habs.get(pre) ?? new Hab(group, this.db, this.ks, this.mgr, this.cf, this.rtr, this.rvy, this.kevery, ns, pre);
-        this.persistGroupHabRecord(pre, group, mhab.pre, signingMembers, rotationMembers, ns);
+        this.persistGroupHabRecord(pre, group, mhab.pre, signingMembers, rotationMembers, ns, existingRecord ?? undefined);
         this.db.groups.add(pre);
         if (hab.accepted) {
             this.markAcceptedGroupHab(pre);
         }
         this.habs.set(pre, hab);
+        if (replacing && !this.readonly) {
+            // The stored lists must follow accepted state, which the old member's record kept from being committed.
+            this.recoverAcceptedGroupMembers(pre);
+            this.retireGroupMemberState(pre, existingRecord.mid);
+        }
         return hab;
     }
+    /**
+     * Drop the durable rows that address `group` to its former local member `old`: registry root copies
+     * escrowed for `old` (the holder check now refuses them, so a retry would only fail) and the markers
+     * of copies sent to `old` as a recipient. Rows keyed by the group itself stay. Live operations are
+     * owned by the runtime and are not reached from here.
+     */
+    retireGroupMemberState(group, old) {
+        for (const [keys] of [...this.db.rrpe.getTopItemIter()]) {
+            const serder = this.db.exns.get([keys.join(".")]);
+            const data = serder?.sad?.a;
+            if (serder?.route === "/registry/root" && serder.sad?.ri === old && data?.gid === group) {
+                this.db.rrpe.rem(keys);
+            }
+        }
+        for (const [keys] of [...this.db.rrsn.getTopItemIter([group])]) {
+            if (keys[2] === old)
+                this.db.rrsn.rem(keys);
+        }
+    }
     /** Commit accepted group member metadata after the corresponding group event is accepted. */
     commitGroupHabMembers(pre, smids, rmids = smids) {
         const record = this.db.getHab(pre);
@@ -1774,12 +1814,15 @@ export class Habery {
         return sigers;
     }
     /** Persist group habitat metadata and member ordinals. */
-    persistGroupHabRecord(pre, group, mid, smids, rmids, ns) {
+    persistGroupHabRecord(pre, group, mid, smids, rmids, ns, replaced) {
         this.db.pinHab(pre, new HabitatRecord({
             hid: pre,
             name: group,
             domain: ns,
             mid,
+            // A rejoin or replacement keeps the rest of the record.
+            sid: replaced?.sid,
+            watchers: replaced?.watchers ? [...replaced.watchers] : undefined,
             smids: [...smids],
             rmids: [...rmids],
         }));
@@ -1878,7 +1921,7 @@ export function branToSeedAeid(bran) {
  * durable DB state rather than depending on process-local creation history.
  */
 export function* openHabery(args) {
-    const { name, base = "", temp = false, headDirPath, compat = false, readonly = false, cf: providedCf, createConfig, skipConfig = false, skipSignator = false, opener, stores, bran, seed, aeid, salt, algo, } = args;
+    const { name, base = "", temp = false, headDirPath, compat = false, readonly = false, cf: providedCf, createConfig, skipConfig = false, skipSignator = false, opener, stores, bran, seed, aeid, salt, algo, heldSigners, } = args;
     let db;
     let ks;
     let cf;
@@ -1921,6 +1964,9 @@ export function* openHabery(args) {
             algo,
             salt: normalizeSaltQb64(salt),
         });
+        // Before the Habery exists, so before any runtime built on it can sign. A bad entry fails the open.
+        if (heldSigners)
+            mgr.hold(heldSigners);
         const hby = new Habery(name, base, temp, headDirPath, compat, readonly, db, ks, mgr, cf, skipSignator, opener, !!stores);
         delivered = true;
         return hby;

package/esm/keri/npm/src/app/identity/keeping.js

@@ -193,6 +193,25 @@ function resolveSuiteCodes(codes, count, code, { label, allowZero = false, }) {
 function emptyLot(dt = "") {
     return new PubLot({ pubs: [], ridx: 0, kidx: 0, dt });
 }
+/**
+ * No private key for `pub`: neither held (`Manager.hold`) nor stored in the Keeper. A custodial host releases
+ * its signers on purpose, so a background loop that needs one treats this as a condition to wait out, not as a
+ * failure of the runtime. The message is the one the Keeper has always used.
+ */
+export class SignerNotHeldError extends Error {
+    constructor(pub) {
+        super(`Missing prikey in db for pubkey=${pub}`);
+        /** The qualified public key whose private key is missing. */
+        Object.defineProperty(this, "pub", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "SignerNotHeldError";
+        this.pub = pub;
+    }
+}
 /**
  * Key-management coordinator backed by `Keeper` state.
  *
@@ -251,6 +270,13 @@ export class Manager {
             writable: true,
             value: new Map()
         });
+        /** Told after `hold()` borrows signers; a loop that waited for a missing signer resumes on it. */
+        Object.defineProperty(this, "holdListeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
         const { ks, seed = "", aeid = "", pidx = 0, algo = Algos.salty, salt = randomSaltQb64(), tier = Tiers.low, } = args;
         this._ks = ks;
         this._seed = seed;
@@ -496,6 +522,17 @@ export class Manager {
         }
         for (const [pub, signer] of batch)
             this.held.set(pub, signer);
+        for (const listener of [...this.holdListeners])
+            listener();
+    }
+    /**
+     * Be told after each `hold()`, so a background loop whose signer was released can resume at once.
+     *
+     * @returns A function that stops the notifications.
+     */
+    onHold(listener) {
+        this.holdListeners.add(listener);
+        return () => this.holdListeners.delete(listener);
     }
     /**
      * Drop held signer references: all of them, or only those for `pubs`.
@@ -519,7 +556,7 @@ export class Manager {
             return held;
         const signer = this.ks.pris.get(pub, this.signerDecrypter());
         if (!signer) {
-            throw new Error(`Missing prikey in db for pubkey=${pub}`);
+            throw new SignerNotHeldError(pub);
         }
         return signer;
     }

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

@@ -50,7 +50,7 @@ import { proposeRegistryEvent } from "../multisig/proposing.js";
 import { envelopeFromFrame } from "../protocol/parsering.js";
 import { exchangeWire } from "./ipex-discloser.js";
 import { acceptedRegistryEvidence, isIssuanceOrigin } from "./ipex-node-authentication.js";
-import { ISSUANCE_QUERY_RESEND_MS, } from "./issuance.js";
+import { ISSUANCE_QUERY_RESEND_MS, partyComplete, } from "./issuance.js";
 /** Milliseconds between scans of the stored wrappers for the final proof. */
 const PROOF_SCAN_MS = 1000;
 /** How many of the group's latest accepted events {@link deriveGroupCustody} considers as coordinators. */
@@ -327,7 +327,7 @@ function* proposalOf(ops, grant, proposal) {
  */
 export function* approveGroupIssuance(ops, grantSaid, options = {}) {
     const { deps, discloser } = ops;
-    if (ops.live.has(grantSaid) || deps.exc.complete(grantSaid)) {
+    if (ops.liveOf(grantSaid, "issuer") || partyComplete(deps, grantSaid, "issuer")) {
         throw new ValidationError("Issuance was already begun for this Grant");
     }
     const { child } = yield* proposalOf(ops, grantSaid, options.proposal);
@@ -413,7 +413,7 @@ function pendingGrant(deps, said) {
  */
 export function approveGroupIssuanceExchange(ops, said, coordinator) {
     const { deps } = ops;
-    if (ops.live.has(said) || deps.exc.complete(said)) {
+    if (ops.liveOf(said, "holder") || partyComplete(deps, said, "holder")) {
         throw new ValidationError("Issuance was already begun for this Grant");
     }
     const { grant, nodes } = pendingGrant(deps, said);
@@ -430,7 +430,7 @@ export function approveGroupIssuanceExchange(ops, said, coordinator) {
  */
 export function* followGroupIssuanceProof(ops, said, options = {}) {
     const { deps } = ops;
-    if (ops.live.has(said) || deps.exc.complete(said)) {
+    if (ops.liveOf(said, "issuer") || partyComplete(deps, said, "issuer")) {
         throw new ValidationError("Issuance was already begun for this Grant");
     }
     const { grant, nodes } = pendingGrant(deps, said);
@@ -647,7 +647,7 @@ export function registerGroupRoutes(ops) {
             acceptsNests: true,
             verify: (args) => structural(deps.hby, args.serder, args.nests ?? []),
             handle: (args) => {
-                for (const op of ops.live.values()) {
+                for (const op of ops.liveOps()) {
                     if (op.group?.accepts(args.serder, args.nests)) {
                         op.group.pending.set(args.serder.said, { wrapper: args.serder, child: args.nests[0] });
                     }
@@ -761,7 +761,10 @@ export function* stepGroup(ops, op) {
         for (const peer of party.others())
             yield* send(peer, msg);
     };
-    if (deps.exc.complete(grant))
+    // The accepted Grant is one fact of the Habery. A holder in the issuer's own Habery is not finished by the issuer
+    // finishing it: its key exchange completes, and its proof goes to its members, in its own steps.
+    const issuerHere = op.role === "holder" && deps.hby.habs.has(g.grant.pre);
+    if (deps.exc.complete(grant) && (!issuerHere || g.mode === "resumed"))
         return true;
     if (op.expires === null) {
         const deadline = deps.exc.exchangeDeadline(g.grant);

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

@@ -40,7 +40,8 @@ export function ipexExnBody(sender, route, nodes, options) {
             throw new Error("IPEX reply parties do not match the prior.");
         }
         if (verb === "spurn" && prior.route === "/ipex/grant" && prior.sad.p) {
-            throw new Error("Only an opening grant may be spurned.");
+            throw new Error("Only a flow-starting Grant (one with no prior) may be spurned; a Grant that answers an Apply or Agree has no "
+                + "rejection message, so do not Admit it and keep it as evidence.");
         }
         recipient = prior.pre;
         xid = prior.ilk === "xip" ? prior.said : prior.sad.x;

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

@@ -25,6 +25,12 @@ import { ipexExnBody, prepareIpexExn } from "./ipex-building.js";
 import { walkIpexGraph } from "./ipex-graph.js";
 import { acceptedRegistryEvidence, authenticateIpexNode, issuedNodeVerdict } from "./ipex-node-authentication.js";
 import { ipexGrantWalk } from "./ipex-v2.js";
+/** Refuse the builder's `prior` where the disclosure API names the prior exchange by `priorSaid`. */
+function refuseBuilderPrior(options) {
+    if (options.prior !== undefined) {
+        throw new ValidationError("Name the prior exchange with priorSaid; prior is not a disclosure option.");
+    }
+}
 /** Reuse a matching accepted KEL seal, or author once and gather real witness receipts. */
 export function* anchorExchange(hby, receiptor, hab, body, auths) {
     if (receiptor.hby !== hby)
@@ -61,8 +67,10 @@ export function exchangeWire(hab, exn, nested = new Uint8Array(), source, gvrsn
     return concatBytes(Counter.makeGVC(gvrsn), exn.raw, Counter.enclose({ qb64: concatBytes(proof, nested), version: gvrsn }));
 }
 /**
- * Re-encode a signed exchange from its retained, authenticated factors: the wire its signer sent, rebuilt
- * from the stored signatures or source seal and the stored nests. Signs nothing, so it needs no keys.
+ * Re-encode a signed exchange from its retained, authenticated factors: the exact bytes its signer presented,
+ * rebuilt from the stored signatures or source seal and the stored nests (`runtime.exc.retainedInput(said)` supplies
+ * them). Signs nothing, so it needs no keys. Public: a host that must hand the presented bytes to a third party
+ * reads them with this instead of re-signing.
  */
 export function* storedExchangeWire(retained, gvrsn = Vrsn_2_0) {
     const nests = [...retained.nests ?? []];
@@ -367,22 +375,30 @@ export class IpexDiscloser {
     }
     /** Create an application request; no credential-use approval is invented for negotiation. */
     *prepareApply(sender, options) {
-        const hab = this.signer(sender, options.gvrsn ?? Vrsn_2_0), exn = ipexExnBody(sender, "/ipex/apply", [], options);
+        const hab = this.signer(sender, options.gvrsn ?? Vrsn_2_0), exn = this.applyBody(sender, options);
         return {
             exn,
             wire: exchangeWire(hab, exn, undefined, undefined, options.gvrsn ?? Vrsn_2_0),
             support: new Uint8Array(),
         };
     }
+    /** The unsigned Apply body, for a sender that signs elsewhere (a group's members each sign their share). */
+    applyBody(sender, options) {
+        return ipexExnBody(sender, "/ipex/apply", [], options);
+    }
     /** Accept or decline the exact authenticated predecessor and its negotiated anchoring choice. */
     *prepareReply(sender, verb, priorSaid, message = "", recipient, auths) {
-        const hab = this.signer(sender), prior = yield* this.prior(priorSaid);
-        const exn = ipexExnBody(sender, `/ipex/${verb}`, [], { message, prior, recipient });
+        const hab = this.signer(sender), exn = yield* this.replyBody(sender, verb, priorSaid, message, recipient);
         const source = verb === "agree" && exn.sad.a.ax?.[0]
             ? yield* anchorExchange(this.hby, this.receiptor, hab, exn, auths)
             : undefined;
         return { exn, wire: exchangeWire(hab, exn, undefined, source), support: source ? this.kel(hab) : new Uint8Array() };
     }
+    /** The unsigned Agree or Spurn body answering an accepted, authenticated predecessor. */
+    *replyBody(sender, verb, priorSaid, message = "", recipient) {
+        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;
@@ -463,15 +479,22 @@ export class IpexDiscloser {
     }
     /** Offer only the selected commitment/view without issuer proof attachments. */
     *prepareOffer(sender, selection, options) {
-        const hab = this.signer(sender, options.gvrsn ?? Vrsn_2_0), prior = yield* this.prior(options.priorSaid);
-        const raw = yield* this.selected(selection, true);
-        const [exn, nests] = yield* prepareIpexExn(sender, "/ipex/offer", raw, { ...options, prior });
+        const hab = this.signer(sender, options.gvrsn ?? Vrsn_2_0);
+        const { exn, nests } = yield* this.prepareOfferBody(sender, selection, options);
         return {
             exn,
             wire: exchangeWire(hab, exn, nests, undefined, options.gvrsn ?? Vrsn_2_0),
             support: new Uint8Array(),
         };
     }
+    /** Freeze an Offer body and its nested evidence without signing, for a sender that signs elsewhere. */
+    *prepareOfferBody(sender, selection, options) {
+        refuseBuilderPrior(options);
+        const prior = yield* this.prior(options.priorSaid);
+        const raw = yield* this.selected(selection, true);
+        const [exn, nests] = yield* prepareIpexExn(sender, "/ipex/offer", raw, { ...options, prior });
+        return { exn, nests };
+    }
     /** Select and authorize once before freezing a Grant body, without signing or committing group approval. */
     *prepareGrantBody(sender, selection, options) {
         return yield* this.grantBody(sender, selection, options, false);
@@ -482,6 +505,7 @@ export class IpexDiscloser {
     }
     /** Both public preparation profiles preserve the same selected view and body construction. */
     *grantBody(sender, selection, options, pendingPresentation) {
+        refuseBuilderPrior(options);
         const hab = this.hby.habs.get(sender);
         if (!hab?.kever || (options.gvrsn ?? Vrsn_2_0).major < 2) {
             throw new ValidationError("ACDC v2 Grant preparation requires an accepted local sender and attachment genus 2.");