keri-ts 1.0.0 → 2.0.1

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;
@@ -262,14 +262,26 @@ Object.defineProperty(DelegateRequestHandler, "resource", {
  *   learned locally and pinned into `aess.`
  */
 export class Anchorer {
-    constructor(hby, { poster, querying, services = defaultRuntimeServices, reactor }) {
+    /**
+     * 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,
@@ -282,41 +294,61 @@ export class Anchorer {
             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
         });
-        Object.defineProperty(this, "reactor", {
+        /** 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 (reactor && reactor.hby !== hby)
-            throw new RangeError("Anchorer Reactor must own the same Habery");
+        if (protocol && protocol.kvy.db !== hby.db) {
+            throw new RangeError("Anchorer protocol processor must use the same database");
+        }
         this.hby = hby;
-        this.reactor = reactor;
-        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);
@@ -391,6 +423,7 @@ export class Anchorer {
     }
     /** 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)));
@@ -403,6 +436,12 @@ export class Anchorer {
         }
         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;
@@ -459,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
@@ -490,6 +543,7 @@ export class Anchorer {
             reason: `Forwarded delegated event ${said} to delegator ${delpre} through ${communicationHab.pre}.`,
         };
     }
+    /** 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;
@@ -555,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);
@@ -568,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) {
@@ -578,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);
@@ -651,11 +708,13 @@ export class Anchorer {
         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) {
@@ -663,6 +722,11 @@ export class Anchorer {
         }
         return localGroupMember(this.hby, hab.pre) ?? this.communicationHab(serder, hab);
     }
+    /**
+     * 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");
@@ -675,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, this.services, this.reactor);
+                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, this.services, this.reactor);
+            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,13 +1,14 @@
-import { concatBytes, Diger, Ilks } from "cesr-ts";
-import { ValidationError } from "../core/errors.js";
-import { reply as replyEvent } from "../core/protocol-eventing.js";
-import { exchange } from "../core/protocol-exchanging.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 } from "./grouping.js";
-const MULTISIG_TOPIC = "multisig";
-export { groupSigningMembers, isLocalGroupHab, localGroupMember } from "./group-members.js";
+import { Diger, Ilks } from "cesr-ts";
+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;
@@ -20,42 +21,41 @@ 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 proposals = [];
-    const deliveries = [];
-    for (const recipient of uniqueMembers(groupSigningMembers(runtime.hby, groupHab.pre))) {
-        if (recipient === member.pre || runtime.hby.habs.has(recipient)) {
-            continue;
-        }
+    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 message = concatBytes(member.endorse(serder, { pipelined: false }), attachments);
-        yield* runtime.reactor.processBytes(message, { local: true });
-        const result = yield* runtime.poster.sendPreparedExchange(member, {
-            recipient,
-            serder,
-            message,
-            topic: MULTISIG_TOPIC,
-        });
-        proposals.push({ recipient, said: serder.said });
-        deliveries.push(...result.deliveries);
+        const prepared = signGroupMessage(member, recipient, [serder, attachments]);
+        outcomes.push(yield* admitAndSendGroupMessage(input, postman, prepared));
     }
     return {
         route: MULTISIG_RPY_ROUTE,
-        proposals,
+        ...groupSendResult(outcomes),
         group: groupHab.pre,
-        accepted: endpointRoleAccepted(runtime.hby, groupHab.pre, role, args.eid),
-        deliveries,
+        accepted: endpointRoleAccepted(hby, groupHab.pre, role, args.eid),
         rpy: localRpy,
     };
 }