keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/app/{challenging.js → identity/challenging.js}

@@ -19,6 +19,8 @@ const CHALLENGE_CONSONANTS = [
 ];
 const CHALLENGE_VOWELS = ["a", "e", "i", "o"];
 const BITS_PER_WORD = 12;
+/** Built-in challenge route; the EXN sender is the authenticated responder. */
+export const CHALLENGE_RESPONSE_ROUTE = "/challenge/response";
 /**
  * Register the built-in challenge-response route handler on one exchanger.
  *
@@ -57,8 +59,7 @@ export class ChallengeHandler {
         this.db = db;
     }
     verify(args) {
-        const payload = args.serder.ked?.a;
-        return challengeWordsFromPayload(payload) !== null
+        return challengeWordsFromPayload(args.serder.ked?.a) !== null
             && args.attachments.length === 0;
     }
     handle(args) {
@@ -74,7 +75,7 @@ Object.defineProperty(ChallengeHandler, "resource", {
     enumerable: true,
     configurable: true,
     writable: true,
-    value: "/challenge/response"
+    value: CHALLENGE_RESPONSE_ROUTE
 });
 /** Return one accepted challenge-response exchange message whose words match `expected`. */
 export function findVerifiedChallengeResponse(db, signer, expected) {
@@ -102,7 +103,7 @@ export function parseChallengeWords(input) {
     const trimmed = input.trim();
     if (trimmed.startsWith("[")) {
         const parsed = JSON.parse(trimmed);
-        if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
+        if (!isChallengeWords(parsed)) {
             throw new Error("Challenge words JSON must be an array of strings.");
         }
         return parsed.map((item) => item.trim()).filter((item) => item.length > 0);
@@ -154,10 +155,14 @@ function challengeWordsEqual(actual, expected) {
     return actual.length === expected.length
         && actual.every((word, index) => word === expected[index]);
 }
+/** Narrow decoded EXN attributes before the handler or verifier reads known challenge content. */
 function challengeWordsFromPayload(payload) {
-    const words = payload?.words;
-    if (!Array.isArray(words) || words.some((item) => typeof item !== "string")) {
+    if (!payload || typeof payload !== "object" || !("words" in payload))
         return null;
-    }
-    return words;
+    const words = payload.words;
+    return isChallengeWords(words) ? words : null;
+}
+/** CLI JSON and decoded response content share the same word-list contract. */
+function isChallengeWords(value) {
+    return Array.isArray(value) && value.every((word) => typeof word === "string");
 }

package/esm/keri/npm/src/app/{configing.js → identity/configing.js}

@@ -1,7 +1,7 @@
-import * as dntShim from "../_dnt.shims.js";
-import { basename, dirname, join } from "../deps/jsr.io/@std/path/1.1.6/mod.js";
-import { ValidationError } from "../core/errors.js";
-import { PathManager } from "../db/core/path-manager.js";
+import * as dntShim from "../../_dnt.shims.js";
+import { basename, dirname, join } from "../../deps/jsr.io/@std/path/1.1.6/mod.js";
+import { ValidationError } from "../../core/errors.js";
+import { PathManager } from "../../db/core/path-manager.js";
 const CONFIGER_DEFAULTS = {
     tailDirPath: "keri/cf",
     cleanTailDirPath: "keri/clean/cf",

package/esm/keri/npm/src/app/{delegating.js → identity/delegating.js}

@@ -13,13 +13,13 @@
  *   side effect
  */
 import { Diger } from "cesr-ts";
-import { ValidationError } from "../core/errors.js";
-import { DELEGATE_MAILBOX_TOPIC, REPLAY_MAILBOX_TOPIC } from "../core/mailbox-topics.js";
-import { Schemes } from "../core/schemes.js";
-import { dgKey } from "../db/core/keys.js";
+import { ValidationError } from "../../core/errors.js";
+import { DELEGATE_MAILBOX_TOPIC, REPLAY_MAILBOX_TOPIC } from "../../core/mailbox/mailbox-topics.js";
+import { Schemes } from "../../core/schemes.js";
+import { dgKey } from "../../db/core/keys.js";
+import { createExchangeMessage } from "../exchanges/exchange-messaging.js";
+import { sendWitnessMessage } from "../witness/receipt-client.js";
 import { eventPayloadMessage, eventReplayMessage } from "./habbing.js";
-import { defaultRuntimeServices } from "./runtime-services.js";
-import { sendWitnessMessage } from "./witnessing.js";
 export const DELEGATE_REQUEST_ROUTE = "/delegate/request";
 /** Runtime passes to wait between repeated delegator-witness anchor queries. */
 const DELEGATION_ANCHOR_QUERY_RETRY_PASSES = 8;
@@ -249,7 +249,7 @@ Object.defineProperty(DelegateRequestHandler, "resource", {
  *   - `cdel.` for completed delegation workflows
  * - outbound correspondence is delegated to `Poster`
  * - delegation-specific anchor discovery stays explicit here and uses
- *   `QueryCoordinator` only as the queued query-delivery seam
+ *   a concrete query producer port; composition owns its consuming worker
  * - witness republication sends the resolved delegator chain directly to the
  *   delegate's witnesses so the flow stays readable against KERIpy
  *
@@ -262,51 +262,93 @@ Object.defineProperty(DelegateRequestHandler, "resource", {
  *   learned locally and pinned into `aess.`
  */
 export class Anchorer {
-    constructor(hby, { poster, querying, services = defaultRuntimeServices }) {
+    /**
+     * Bind delivery/query/protocol collaborators from the same accepted-state domain; acquire no stores.
+     *
+     * @param hby Borrowed local identities and accepted-state stores.
+     * @param postman Borrowed Poster; its delivery worker must run while this operation awaits outcomes.
+     * @param querying Borrowed query-admission owner for anchor discovery.
+     * @param protocol Same-database reply processor, or null when receive support is absent.
+     * @param http Borrowed HTTP implementation selected by composition.
+     * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+     */
+    constructor(hby, postman, querying, protocol, http, clock) {
+        /** Borrowed identities and durable delegation escrow stores. */
         Object.defineProperty(this, "hby", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "poster", {
+        /** Queued delivery owner; phase transitions wait for the matching successful outcome. */
+        Object.defineProperty(this, "postman", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Query producer port; composition owns the consuming coordinator and its lifetime. */
         Object.defineProperty(this, "querying", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "services", {
+        /** Borrowed HTTP and clock services for witness publication. */
+        Object.defineProperty(this, "http", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Borrowed clock for this owner's actual network deadlines. */
+        Object.defineProperty(this, "clock", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Borrowed receive processing for witness sends; absent explicitly permits transmit-only delivery. */
+        Object.defineProperty(this, "protocol", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Process-local proxy selection per delegated event; cleared when the workflow ends. */
         Object.defineProperty(this, "communicationHabPins", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new Map()
         });
+        /** Existing query retry-pass bookkeeping; independent of Poster delivery retry. */
         Object.defineProperty(this, "anchorQueryRetryPasses", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new Map()
         });
+        if (protocol && protocol.kvy.db !== hby.db) {
+            throw new RangeError("Anchorer protocol processor must use the same database");
+        }
         this.hby = hby;
-        this.poster = poster;
+        this.protocol = protocol;
+        this.postman = postman;
         this.querying = querying;
-        this.services = services;
-    }
+        this.http = http;
+        this.clock = clock;
+    }
+    /**
+     * Start one delegated event in witness-receipt escrow and replace any previous local proxy pin.
+     *
+     * @param serder Delegated event whose witness/approval workflow is started or reset.
+     * @param options Optional communicationHab pins a local proxy signer for this process.
+     */
     begin(serder, options = {}) {
         const key = eventKey(serder);
         const id = workflowId(serder);
+        // Reset durable phase membership before pinning this process's communication signer.
         this.hby.db.dpwe.pin(key, serder);
         this.hby.db.dune.rem(key);
         this.hby.db.dpub.rem(key);
@@ -379,22 +421,27 @@ export class Anchorer {
         }
         return false;
     }
-    /** Process delegation escrows; an active runtime lends its same-socket TCP reply receiver. */
-    *processAllOnce(runtime) {
-        if (runtime && runtime.hby !== this.hby)
-            throw new RangeError("Anchorer requires its owning runtime");
+    /** Advance delegation escrows using the protocol receiver selected at construction. */
+    *processAllOnce() {
+        // A pass advances the existing phases in dependency order, using finite escrow snapshots.
         const results = [];
         for (const [keys, serder] of [...this.hby.db.dpwe.getTopItemIter()]) {
             results.push(yield* this.processPartialWitnessEscrow(escrowContext(keys, serder)));
         }
         for (const [keys, serder] of [...this.hby.db.dune.getTopItemIter()]) {
-            results.push(yield* this.processUnanchoredEscrow(escrowContext(keys, serder), runtime));
+            results.push(yield* this.processUnanchoredEscrow(escrowContext(keys, serder)));
         }
         for (const [keys, serder] of [...this.hby.db.dpub.getTopItemIter()]) {
             results.push(yield* this.processWitnessPublication(escrowContext(keys, serder)));
         }
         return results;
     }
+    /**
+     * Require delegate receipts, deliver the approval request/event, then move to anchor discovery. Failed delivery leaves this phase retained.
+     *
+     * @param context Escrow key, event, prefix and SAID resolved from durable workflow state.
+     * @returns Current delegation phase result; failed transmission does not advance to anchor discovery.
+     */
     *processPartialWitnessEscrow(context) {
         const [keys, serder, pre, said] = context;
         let hab;
@@ -451,21 +498,35 @@ export class Anchorer {
         // have receipted the event. That preserves the KERIpy approval ordering
         // and avoids anchoring an event the delegate cannot yet complete.
         const message = eventPayloadMessage(this.hby, serder);
-        yield* this.poster.sendExchange(communicationHab, {
-            recipient: delpre,
+        const { msg } = createExchangeMessage(communicationHab, {
+            dest: delpre,
             exchangeRecipient: null,
             route: DELEGATE_REQUEST_ROUTE,
             payload: {
                 delpre,
             },
-            topic: DELEGATE_MAILBOX_TOPIC,
             embeds: { evt: message },
         });
-        yield* this.poster.sendBytes(communicationHab, {
-            recipient: delpre,
-            message,
+        const postman = this.postman;
+        const request = postman.send({
+            src: communicationHab.pre,
+            dest: delpre,
+            msg,
             topic: DELEGATE_MAILBOX_TOPIC,
-        });
+        }, { notify: true });
+        // Admission alone cannot release the next send or the delegation phase transition.
+        const requested = yield* postman.wait(request);
+        if (requested.kin === "failed")
+            throw requested.error;
+        const replay = postman.send({
+            src: communicationHab.pre,
+            dest: delpre,
+            msg: message,
+            topic: DELEGATE_MAILBOX_TOPIC,
+        }, { notify: true });
+        const replayed = yield* postman.wait(replay);
+        if (replayed.kin === "failed")
+            throw replayed.error;
         // KERIpy issues the first delegator-witness anchor query in the same
         // publish phase that forwards the delegation request and raw event bytes.
         // Keep that ordering here so delegate-side approval discovery does not
@@ -482,7 +543,8 @@ export class Anchorer {
             reason: `Forwarded delegated event ${said} to delegator ${delpre} through ${communicationHab.pre}.`,
         };
     }
-    *processUnanchoredEscrow(context, runtime) {
+    /** Wait for locally accepted delegator evidence; pin its seal before completing or publishing to witnesses. */
+    *processUnanchoredEscrow(context) {
         const [keys, serder, pre, said] = context;
         let hab;
         try {
@@ -536,7 +598,7 @@ export class Anchorer {
                 reason: "Delegator approval is anchored and no witness republication is required.",
             };
         }
-        yield* this.publishDelegator(serder, runtime);
+        yield* this.publishDelegator(serder);
         this.hby.db.dpub.pin(keys, serder);
         return {
             kind: "advance",
@@ -547,6 +609,7 @@ export class Anchorer {
             reason: "Delegator approval is anchored; published the delegation chain to delegate witnesses.",
         };
     }
+    /** Record durable completion only after the preceding publication operation has succeeded. */
     *processWitnessPublication(context) {
         const [keys, serder, pre, said] = context;
         this.hby.db.dpub.rem(keys);
@@ -560,6 +623,7 @@ export class Anchorer {
             reason: "Witness publication completed after delegator approval.",
         };
     }
+    /** Use the pinned proxy for inception or the existing delegate for rotation; never guess an inception signer. */
     communicationHab(serder, hab = workflowHab(this.hby, serder)) {
         const pinned = this.communicationHabPins.get(workflowId(serder));
         if (pinned) {
@@ -570,6 +634,7 @@ export class Anchorer {
         }
         throw new ValidationError(`Delegated inception for ${hab.pre} requires --proxy <alias> to send delegation requests.`);
     }
+    /** Publish the initial anchor query after successful sending and seed the existing retry-pass bookkeeping. */
     queueDelegatorWitnessQueryNow(serder, communicationHab) {
         const id = workflowId(serder);
         const delpre = delegatedWorkflowDelpre(this.hby, serder);
@@ -587,8 +652,8 @@ export class Anchorer {
         this.querying.enqueue({
             pre: delpre,
             route: "logs",
-            query: { fn: "0", s: "0", a: eventAnchor(serder) },
-            hab: communicationHab,
+            q: { fn: "0", s: "0", a: eventAnchor(serder) },
+            signer: communicationHab.pre,
             wits: [witness],
         });
         // Mark that an immediate publication-time query was already sent so the
@@ -619,8 +684,8 @@ export class Anchorer {
             this.querying.enqueue({
                 pre: delpre,
                 route: "logs",
-                query: { fn: "0", s: "0", a: eventAnchor(serder) },
-                hab: communicationHab,
+                q: { fn: "0", s: "0", a: eventAnchor(serder) },
+                signer: communicationHab.pre,
                 wits: [witness],
             });
             this.anchorQueryRetryPasses.set(id, 0);
@@ -636,18 +701,20 @@ export class Anchorer {
         this.querying.enqueue({
             pre: delpre,
             route: "logs",
-            query: { fn: "0", s: "0", a: eventAnchor(serder) },
-            hab: communicationHab,
+            q: { fn: "0", s: "0", a: eventAnchor(serder) },
+            signer: communicationHab.pre,
             wits: [witness],
         });
         this.anchorQueryRetryPasses.set(id, 0);
         return `Delegator anchor has not been learned locally yet; queried delegator witness ${witness}.`;
     }
+    /** Retire only this event's process-local signer and query bookkeeping. */
     clearWorkflowPins(serder) {
         const id = workflowId(serder);
         this.communicationHabPins.delete(id);
         this.anchorQueryRetryPasses.delete(id);
     }
+    /** Choose the pinned proxy, local group member or existing communication habitat for publication. */
     publicationTransportHab(serder, hab) {
         const pinned = this.communicationHabPins.get(workflowId(serder));
         if (pinned) {
@@ -655,7 +722,12 @@ export class Anchorer {
         }
         return localGroupMember(this.hby, hab.pre) ?? this.communicationHab(serder, hab);
     }
-    *publishDelegator(serder, runtime) {
+    /**
+     * Send the delegation chain before the approving event, awaiting actual Poster or witness transmission outcomes.
+     *
+     * @param serder Accepted delegator event to publish after its required delegation chain.
+     */
+    *publishDelegator(serder) {
         const pre = workflowPre(serder);
         const hab = localHabByPre(this.hby, pre, "Delegation witness publication");
         const transportHab = this.publicationTransportHab(serder, hab);
@@ -667,19 +739,25 @@ export class Anchorer {
         // matches the witness-visible material KERIpy sends for delegated approval.
         for (const msg of this.hby.db.cloneDelegation(kever)) {
             for (const witness of kever.wits) {
-                yield* sendWitnessMessage(transportHab, witness, msg, undefined, runtime?.services ?? this.services, runtime);
+                yield* sendWitnessMessage(transportHab, witness, msg, this.http, this.clock, this.protocol);
             }
         }
+        // Publish the approving event only after the complete delegation chain has been sent.
         const approvedEvent = eventReplayMessage(this.hby, kever.serder);
         if (kever.delpre) {
-            yield* this.poster.sendBytes(transportHab, {
-                recipient: kever.delpre,
+            const postman = this.postman;
+            const evt = postman.send({
+                src: transportHab.pre,
+                dest: kever.delpre,
                 topic: REPLAY_MAILBOX_TOPIC,
-                message: approvedEvent,
-            });
+                msg: approvedEvent,
+            }, { notify: true });
+            const outcome = yield* postman.wait(evt);
+            if (outcome.kin === "failed")
+                throw outcome.error;
         }
         for (const witness of kever.wits) {
-            yield* sendWitnessMessage(transportHab, witness, approvedEvent, undefined, runtime?.services ?? this.services, runtime);
+            yield* sendWitnessMessage(transportHab, witness, approvedEvent, this.http, this.clock, this.protocol);
         }
     }
 }

package/esm/keri/npm/src/app/{endpoint-roleing.js → identity/endpoint-roleing.js}

@@ -1,12 +1,14 @@
 import { Diger, Ilks } from "cesr-ts";
-import { ValidationError } from "../core/errors.js";
-import { reply as replyEvent } from "../core/protocol-eventing.js";
-import { messagize } from "../core/protocol-serialization.js";
-import { Roles } from "../core/roles.js";
-import { groupSigningMembers, localGroupMember, uniqueMembers, } from "./group-members.js";
-import { MULTISIG_RPY_ROUTE, multisigRpyExn } from "./grouping.js";
-const MULTISIG_TOPIC = "multisig";
-export { groupSigningMembers, isLocalGroupHab, localGroupMember, } from "./group-members.js";
+import { ValidationError } from "../../core/errors.js";
+import { exchange } from "../../core/exchange/protocol-exchanging.js";
+import { reply as replyEvent } from "../../core/protocol-eventing.js";
+import { messagize } from "../../core/protocol-serialization.js";
+import { Roles } from "../../core/roles.js";
+import { groupSigningMembers, localGroupMember } from "../multisig/group-members.js";
+import { MULTISIG_RPY_ROUTE } from "../multisig/grouping.js";
+import { Reactor } from "../protocol/reactor.js";
+import { admitAndSendGroupMessage, groupSendResult, remoteGroupMembers, signGroupMessage, } from "../multisig/multisig-messaging.js";
+export { groupSigningMembers, isLocalGroupHab, localGroupMember } from "../multisig/group-members.js";
 /** Return whether endpoint-role state currently authorizes `eid` for `cid`. */
 export function endpointRoleAccepted(hby, cid, role, eid) {
     return hby.db.ends.get([cid, role, eid])?.allowed === true;
@@ -19,28 +21,46 @@ export function loadAcceptedEndpointRole(hab, eid, role = Roles.controller) {
     }
     return rpy;
 }
-/** Propose one group endpoint-role reply under `/multisig/rpy`. */
-export function* proposeGroupEndpointRole(runtime, groupHab, args) {
+/**
+ * Propose one group endpoint-role reply under `/multisig/rpy`.
+ *
+ * @param hby Borrowed identities and accepted group state.
+ * @param protocol Shared semantic owner; the proposal owns its local byte-input context.
+ * @param postman Borrowed delivery owner; the caller runs and joins its worker.
+ * @param groupHab Local group habitat whose endpoint-role reply needs member approvals.
+ * @param args Endpoint AID, role and allow/cut decision used to construct the signed proposal.
+ * @returns Proposal identifiers, current acceptance and actual delivery URLs.
+ */
+export function* proposeGroupEndpointRole(hby, protocol, postman, groupHab, args) {
     const role = args.role ?? Roles.mailbox;
-    const member = localGroupMember(runtime.hby, groupHab.pre);
-    const rpySerder = replyEvent(args.allow === false ? "/end/role/cut" : "/end/role/add", { cid: groupHab.pre, role, eid: args.eid }, { pre: groupHab.pre });
-    const localRpy = groupEndorseReply(runtime.hby, groupHab.pre, rpySerder);
-    yield* runtime.reactor.processBytes(localRpy, { local: true });
-    yield* runtime.reactor.processEscrowsOnce();
-    const [exn, attachments] = yield* multisigRpyExn(groupHab, member, localRpy);
-    const deliveries = yield* publishEndpointRoleProposal(runtime, member, groupSigningMembers(runtime.hby, groupHab.pre), { gid: groupHab.pre }, { rpy: localRpy });
+    const input = new Reactor(protocol);
+    if (input.kvy.db !== hby.db)
+        throw new TypeError("Endpoint-role proposal must use the same accepted-state store");
+    const member = localGroupMember(hby, groupHab.pre);
+    const rpySerder = replyEvent(args.allow === false ? "/end/role/cut" : "/end/role/add", { cid: groupHab.pre, role, eid: args.eid }, { pre: groupHab.pre, pvrsn: groupHab.kelVersion });
+    const localRpy = groupEndorseReply(hby, groupHab.pre, rpySerder);
+    yield* input.processBytes(localRpy, { local: true });
+    yield* protocol.processEscrowsOnce();
+    const outcomes = [];
+    for (const recipient of remoteGroupMembers(hby, member, groupSigningMembers(hby, groupHab.pre))) {
+        const [serder, attachments] = exchange(MULTISIG_RPY_ROUTE, { gid: groupHab.pre }, {
+            sender: member.pre,
+            recipient,
+            embeds: { rpy: localRpy },
+        });
+        const prepared = signGroupMessage(member, recipient, [serder, attachments]);
+        outcomes.push(yield* admitAndSendGroupMessage(input, postman, prepared));
+    }
     return {
         route: MULTISIG_RPY_ROUTE,
-        said: exn.said ?? undefined,
+        ...groupSendResult(outcomes),
         group: groupHab.pre,
-        accepted: endpointRoleAccepted(runtime.hby, groupHab.pre, role, args.eid),
-        deliveries,
-        attachmentBytes: attachments.length,
+        accepted: endpointRoleAccepted(hby, groupHab.pre, role, args.eid),
         rpy: localRpy,
     };
 }
 /** Endorse one reply with locally available group member signatures. */
-export function groupEndorseReply(hby, groupPre, serder) {
+export function groupEndorseReply(hby, groupPre, serder, gvrsn) {
     const keys = groupEventKeys(hby, groupPre, serder);
     const sigers = signLocalGroupEvent(hby, serder, groupSigningMembers(hby, groupPre), keys);
     const kever = hby.db.getKever(groupPre);
@@ -54,25 +74,9 @@ export function groupEndorseReply(hby, groupPre, serder) {
         sigers,
         seal: { i: kever.prefixer, s: seqner, d: new Diger({ qb64: estSaid }) },
         pipelined: true,
+        gvrsn,
     });
 }
-function* publishEndpointRoleProposal(runtime, member, recipients, 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: MULTISIG_RPY_ROUTE,
-            payload,
-            embeds,
-            topic: MULTISIG_TOPIC,
-        });
-        deliveries.push(...result.deliveries, ...result.queued);
-    }
-    return deliveries;
-}
 /**
  * Resolve the public keys that should sign one group event or reply.
  *