keri-ts 1.0.0 → 2.0.0

package/esm/keri/npm/src/app/{reply-streams.js → delivery/reply-streams.js}

@@ -16,18 +16,40 @@ export class ReplyStreams {
             value: false
         });
     }
-    /** Borrow a reopenable source without advancing until HTTP requests bytes.
+    /**
+     * Acquire one source iterator without advancing until HTTP requests bytes.
      * Transfer the optional disposer through source closure, including acquisition failure.
+     *
+     * @param messages Synchronous wire-message iterable; its iterator remains owned by the response until EOF/cancel/close.
+     * @param dispose Cleanup callback retained through iterator closure; invoked once even if acquisition fails.
+     * @returns Request-owned Web stream.
+     * @throws Source or disposer failures propagate; independent cleanup failures are retained.
      */
     open(messages, dispose) {
         return this.openChecked(messages, dispose, false);
     }
-    /** Prime one message; empty output closes ownership for a caller's 404 decision. */
+    /**
+     * Prime one message; empty output closes ownership for a caller's 404 decision.
+     *
+     * @param messages Synchronous wire-message iterable; its iterator remains owned by the response until EOF/cancel/close.
+     * @param dispose Cleanup callback retained through iterator closure; invoked once even if acquisition fails.
+     * @returns Request-owned Web stream, or null after empty-source cleanup.
+     * @throws Source or disposer failures propagate; independent cleanup failures are retained.
+     */
     openNonEmpty(messages, dispose) {
         return this.openChecked(messages, dispose, true);
     }
-    /** Optional priming shares the same response owner/disposer; ordinary open always returns a stream. */
+    /**
+     * Optional priming shares the same response owner/disposer; ordinary open always returns a stream.
+     *
+     * @param messages Synchronous wire-message iterable; its iterator remains owned by the response until EOF/cancel/close.
+     * @param dispose Cleanup callback retained through iterator closure; invoked once even if acquisition fails.
+     * @param requireContent Prime one nonempty message before publishing; empty sources close and return null.
+     * @returns Request-owned Web stream, or null after empty-source cleanup.
+     * @throws Source or disposer failures propagate; independent cleanup failures are retained.
+     */
     openChecked(messages, dispose, requireContent) {
+        /** Detach the optional disposer before invoking it so acquisition failure cannot run it twice. */
         const release = () => {
             const owned = dispose;
             dispose = undefined;
@@ -46,13 +68,24 @@ export class ReplyStreams {
             throw error;
         }
     }
-    /** Keep the optional disposer through iterator cleanup, including cancellation before the first pull. */
+    /**
+     * Keep the optional disposer through iterator cleanup, including cancellation before the first pull.
+     *
+     * @param messages Synchronous wire-message iterable; its iterator remains owned by the response until EOF/cancel/close.
+     * @param release Cleanup callback retained through iterator closure; invoked once even if acquisition fails.
+     * @param requireContent Prime one nonempty message before publishing; empty sources close and return null.
+     * @returns Request-owned Web stream, or null after empty-source cleanup.
+     * @throws Source or disposer failures propagate; independent cleanup failures are retained.
+     */
     openOwned(messages, release, requireContent) {
         if (this.closed)
             throw new Error("Reply streams are closed");
         let iterator;
         let current;
-        /** Retain at most one event, ignoring empty source values without acquiring another owner. */
+        /**
+         * Retain at most one event, ignoring empty source values without acquiring another owner.
+         * @returns True when a nonempty message is ready; false at source EOF.
+         */
         const advance = () => {
             while (!current && iterator) {
                 const next = iterator.next();
@@ -63,7 +96,10 @@ export class ReplyStreams {
             }
             return current !== undefined;
         };
-        /** Close unpublished iterators and their disposer before returning or throwing. */
+        /**
+         * Close unpublished iterators and their disposer before returning or throwing.
+         * @param primary Original acquisition/priming failure, retained alongside distinct cleanup failures.
+         */
         const closeUnpublished = (primary) => {
             const errors = primary ? [primary.error] : [];
             const owned = iterator;
@@ -104,7 +140,10 @@ export class ReplyStreams {
             return null;
         }
         let stream;
-        /** Remove ownership exactly once, including when the platform still holds a reader lock. */
+        /**
+         * Remove ownership exactly once, including when the platform still holds a reader lock.
+         * @param reason Failure to publish to the stream, or undefined for ordinary EOF/cancellation cleanup.
+         */
         const close = (reason) => {
             if (!iterator)
                 return;
@@ -138,9 +177,15 @@ export class ReplyStreams {
         this.readers.add(close);
         try {
             return new ReadableStream({
+                /**
+                 * Attach the controller to this response lifetime before the first pull.
+                 *
+                 * @param controller Web stream controller retained for subsequent pulls and cancellation.
+                 */
                 start(controller) {
                     stream = controller;
                 },
+                /** Demand transfers one nonempty source message to the response; source failure closes the iterator first. */
                 pull: (controller) => {
                     try {
                         if (!advance()) {

package/esm/keri/npm/src/app/delivery/respondant.js

@@ -0,0 +1,159 @@
+/**
+ * Shared host-side responder for indirect and witness runtimes.
+ *
+ * KERIpy correspondence:
+ * - this is the local analogue of `Respondant` for reply/replay/receipt-style
+ *   cues
+ * - `BaseHab.processCuesIter()` interprets the cue; `Poster` delivers the
+ *   resulting bytes
+ * - mailbox-query `stream` cues stay with mailbox storage/query coordination
+ *
+ * Boundary rule:
+ * - this class constructs signed non-`stream` output and admits it to Poster
+ * - `MailboxDirector` owns provider publication and `stream` cue correlation,
+ *   using its separately owned Mailboxer for actual storage
+ * - ordinary query replies follow this output path rather than returning from
+ *   the HTTP query POST; direct TCP correlation claims its own reply cues first
+ *
+ * Source cue removal proves complete output admission, not delivery. Poster runs
+ * independently and owns routing, transport attempts and failure outcomes. Keep
+ * mailbox provider writes in that routing path, not in responder cue interpretation.
+ */
+export class Respondant {
+    /** Bind borrowed identity and delivery owners without acquiring stores or network lifetimes. */
+    constructor(hby, postman) {
+        /** Borrowed local signer and accepted-state collection. */
+        Object.defineProperty(this, "hby", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Delivery owner; source cues are consumed only after its admission succeeds. */
+        Object.defineProperty(this, "postman", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.hby = hby;
+        this.postman = postman;
+    }
+    /**
+     * Produce a whole cue before publishing or removing it; construction failure leaves the source visible.
+     *
+     * @param hab Local habitat used to construct/sign this output; stores remain borrowed.
+     * @param cues Source Deck; only its current head is interpreted, and removed after full publication.
+     * @param hint Optional local sender hint used when cue provenance does not resolve a habitat.
+     * @returns True after complete admission/removal; false if the head has no routable responder output.
+     * @throws Construction/admission failures leave the source cue present.
+     */
+    enqueueCue(hab, cues, hint) {
+        this.postman.ensureOpen();
+        const cue = cues.peekHead();
+        if (!cue)
+            return false;
+        const dest = recipientForCue(cue), topic = topicForCue(cue);
+        const src = senderHabForCue(this.hby, cue, hint);
+        if (!dest || !topic || !src)
+            return false;
+        const msgs = [...hab.processCuesIter([cue])];
+        this.postman.sendAll(msgs.map((msg) => ({ src: src.pre, dest, topic, msg, replies: true })));
+        cues.pull();
+        return true;
+    }
+    /**
+     * Admit already produced witness messages without signing them again.
+     *
+     * @param hab Local habitat used to construct/sign this output; stores remain borrowed.
+     * @param cue Routing/provenance cue for the already-signed output.
+     * @param msgs Complete signed messages; Poster copies them during atomic admission.
+     */
+    enqueueMsgs(hab, cue, msgs) {
+        const dest = recipientForCue(cue), topic = topicForCue(cue);
+        const src = senderHabForCue(this.hby, cue, hab);
+        if (!dest || !topic || !src)
+            return;
+        this.postman.sendAll(msgs.map((msg) => ({ src: src.pre, dest, topic, msg, replies: true })));
+    }
+}
+/**
+ * Select the existing mailbox topic for a responder cue.
+ *
+ * @param cue Typed cue whose family determines the field meaning.
+ * @returns Mailbox topic or null for a non-responder cue.
+ */
+function topicForCue(cue) {
+    switch (cue.kin) {
+        case "replay":
+            return "/replay";
+        case "reply":
+            return "/reply";
+        case "receipt":
+        case "witness":
+            return "/receipt";
+        default:
+            return null;
+    }
+}
+/**
+ * Select the intended recipient without preparing or transmitting bytes.
+ *
+ * @param cue Typed cue whose family determines the field meaning.
+ * @returns Final recipient AID, or null when this cue has none.
+ */
+function recipientForCue(cue) {
+    switch (cue.kin) {
+        case "replay":
+            return cue.dest ?? null;
+        case "reply":
+            return cue.dest ?? null;
+        case "receipt":
+        case "witness":
+            return cue.serder.pre ?? null;
+        default:
+            return null;
+    }
+}
+/**
+ * Borrow the local sender selected by cue provenance, explicit hint or sole habitat.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param cue Cue whose src may identify a local sender.
+ * @param hab Optional fallback habitat hint.
+ * @returns Cue-selected habitat, hint or sole local habitat; null if unresolved.
+ */
+function senderHabForCue(hby, cue, hab) {
+    const source = cueSourcePrefix(cue);
+    if (source) {
+        return hby.habs.get(source) ?? hab ?? soleHab(hby);
+    }
+    return hab ?? soleHab(hby);
+}
+/**
+ * Read explicit local sender provenance only from cue families that carry it.
+ *
+ * @param cue Typed cue whose family determines the field meaning.
+ * @returns Explicit local sender AID for reply/replay, or null.
+ */
+function cueSourcePrefix(cue) {
+    switch (cue.kin) {
+        case "replay":
+            return cue.src ?? null;
+        case "reply":
+            return cue.src ?? null;
+        default:
+            return null;
+    }
+}
+/**
+ * Use an implicit signer only when the local collection is unambiguous.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @returns The only local habitat, or null for zero/multiple candidates.
+ */
+function soleHab(hby) {
+    const habitats = hby.habs.values();
+    const first = habitats.next();
+    return first.done || !habitats.next().done ? null : first.value;
+}

package/esm/keri/npm/src/app/{stored-replies.js → delivery/stored-replies.js}

@@ -1,9 +1,9 @@
 /** Finite stored endpoint-reply reconstruction; current proof rows are borrowed only during this synchronous call. */
 import { Cigar, Diger, Prefixer, Seqner } from "cesr-ts";
-import { resolveAttachmentGvrsn } from "../core/attachment-countering.js";
-import { TransIdxSigGroup } from "../core/dispatch.js";
-import { DatabaseOperationError } from "../core/errors.js";
-import { messagize } from "../core/protocol-serialization.js";
+import { resolveAttachmentGvrsn } from "../../core/attachment-countering.js";
+import { TransIdxSigGroup } from "../../core/dispatch.js";
+import { DatabaseOperationError } from "../../core/errors.js";
+import { messagize } from "../../core/protocol-serialization.js";
 /**
  * Rebuild one persisted reply with all stored groups and exactly one optional cigar.
  *

package/esm/keri/npm/src/app/exchanges/essr.js

@@ -0,0 +1,111 @@
+/**
+ * ESSR recipient authentication and finite sealed-box decryption.
+ * Exchanger owns signed envelope acceptance and Baser owns retained Texters;
+ * this module reads that accepted evidence for one explicitly selected local Hab.
+ * Protocol authentication is independent of storage and plaintext is not saved.
+ */
+import { Diger, MtrDex, parseBexter, parsePrefixer, ParserError, parseTagger } from "cesr-ts";
+/** Verify and decrypt accepted LMDB evidence for one explicitly hosted recipient. */
+export class EssrRecipient {
+    /** Bind the local key owner; recipient selection never searches other habitats. */
+    constructor(hab) {
+        Object.defineProperty(this, "hab", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: hab
+        });
+    }
+    /**
+     * Read accepted evidence, verify its signed commitment and return authenticated inner bytes.
+     *
+     * Processing is synchronous: LMDB and sealed-box crypto already expose finite bytes.
+     * The result has no file/disposal lifecycle and is never persisted automatically.
+     * Envelope checks bind the EXN sender/source and destination to this local Hab;
+     * the decrypted SCS header must repeat the authenticated sender. Verify the
+     * signed digest over stored Texter raw bytes before attempting decryption.
+     *
+     * Baser follows pinned-main ordered-set semantics: repeated identical Texters
+     * can be lost during persistence. Such retained evidence fails this digest check
+     * rather than returning unauthenticated plaintext. See the repeated-fragment
+     * report in docs/reports/essr for the known reference limitation.
+     *
+     * @param said Accepted outer ESSR EXN SAID, not the payload digest.
+     * @returns Typed absence, authentication/framing rejection or authenticated bytes.
+     * @throws Corrupt stored identity, missing local key state and storage/crypto
+     * infrastructure failures propagate; only actual sealed-box authentication failure
+     * becomes a decrypt rejection.
+     */
+    decrypt(said) {
+        const serder = this.hab.db.exns.get([said]);
+        if (!serder)
+            return { kind: "refuse", reason: "unaccepted" };
+        if (serder.said !== said)
+            throw new Error("Stored ESSR exchange SAID does not match its key");
+        const modifiers = serder.ked?.q;
+        if (serder.ilk !== "exn" || serder.route !== "/essr/req"
+            || !serder.pre || modifiers?.src !== serder.pre
+            || modifiers?.dest !== this.hab.pre || !this.hab.db.prefixes.has(this.hab.pre)
+            || typeof serder.a !== "string")
+            return { kind: "reject", reason: "envelope" };
+        const verfer = this.hab.kever?.verfers[0];
+        if (!verfer)
+            throw new Error("ESSR recipient has no accepted verification key");
+        let diger;
+        try {
+            diger = new Diger({ qb64: serder.a });
+        }
+        catch (error) {
+            if (error instanceof ParserError)
+                return { kind: "reject", reason: "envelope" };
+            throw error;
+        }
+        const fragments = this.hab.db.getEssrs(said);
+        if (!fragments || !diger.verifyChunks(fragments.map((part) => part.raw))) {
+            return { kind: "reject", reason: "digest" };
+        }
+        const sealed = new Uint8Array(fragments.reduce((size, part) => size + part.raw.length, 0));
+        let at = 0;
+        for (const part of fragments) {
+            sealed.set(part.raw, at);
+            at += part.raw.length;
+        }
+        if (sealed.length < 48)
+            return { kind: "reject", reason: "envelope" };
+        // Only authentication failure returns null. Keeper and backend failures propagate.
+        const plain = this.hab.mgr.open(sealed, verfer);
+        if (plain === null)
+            return { kind: "reject", reason: "decrypt" };
+        const offset = bodyOffset(plain, serder.pre);
+        if (offset === null) {
+            plain.fill(0);
+            return { kind: "reject", reason: "framing" };
+        }
+        return {
+            kind: "accept",
+            message: { sender: serder.pre, recipient: this.hab.pre, body: plain.subarray(offset) },
+        };
+    }
+}
+/** Read KERIpy's text-qualified SCS tag, source prefix, and variable padding. */
+function bodyOffset(plain, sender) {
+    try {
+        const tag = parseTagger(plain, "txt");
+        if (tag.code !== MtrDex.Tag3 || tag.tag !== "SCS")
+            return null;
+        const prefix = parsePrefixer(plain.subarray(tag.fullSize), "txt");
+        if (prefix.qb64 !== sender)
+            return null;
+        const paddingAt = tag.fullSize + prefix.fullSize;
+        const padding = parseBexter(plain.subarray(paddingAt), "txt");
+        const offset = paddingAt + padding.fullSize;
+        if (offset >= plain.length)
+            return null;
+        return offset;
+    }
+    catch (error) {
+        if (error instanceof ParserError)
+            return null;
+        throw error;
+    }
+}

package/esm/keri/npm/src/app/exchanges/exchange-messaging.js

@@ -0,0 +1,66 @@
+import { Organizer } from "../identity/organizing.js";
+/** Construct signed exchanges in their producer and run standalone queued sends. */
+import { concatBytes, Vrsn_1_0 } from "cesr-ts";
+import { call, resource, spawn } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { exchange } from "../../core/exchange/protocol-exchanging.js";
+import { Poster } from "../delivery/forwarding.js";
+import { mailboxTopicForRoute } from "../mailbox/topic-routing.js";
+/**
+ * Sign the producer's exchange once, including any independently framed embedded material.
+ *
+ * @param hab Local signing habitat; its state/store lifetime remains with the caller.
+ * @param args Resolved recipient, route and business fields; optional embeds carry independently framed wire.
+ * @returns Signed EXN body plus complete message bytes; this performs no delivery.
+ */
+export function createExchangeMessage(hab, args) {
+    const embeds = args.embeds ?? {};
+    const embedded = Object.keys(embeds).length > 0;
+    const [serder, attachments] = exchange(args.route, args.payload, {
+        // Like KERIpy Hab.exchange, plain exchanges follow the habitat's KEL version;
+        // pathed embeds exist only in the legacy v1 exchange body.
+        pvrsn: args.pvrsn ?? (embedded ? Vrsn_1_0 : hab.kelVersion),
+        sender: hab.pre,
+        recipient: args.exchangeRecipient === null ? undefined : args.exchangeRecipient ?? args.dest,
+        modifiers: args.modifiers,
+        stamp: args.date,
+        dig: args.dig,
+        embeds: embedded ? embeds : undefined,
+    });
+    return { serder, msg: concatBytes(hab.endorse(serder, { pipelined: false }), attachments) };
+}
+/**
+ * Run a standalone command's Poster and await actual delivery before closing its worker.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param hab Local signing habitat; its state/store lifetime remains with the caller.
+ * @param http Borrowed HTTP implementation selected by composition.
+ * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+ * @param args Exchange fields plus optional mailbox topic; recipient aliases are resolved before signing.
+ * @returns Signed EXN and successfully delivered target URLs after the worker/Poster scope joins.
+ * @throws A failed terminal outcome is thrown; admission alone never returns success.
+ */
+export function sendExchangeMessage(hby, hab, http, clock, args) {
+    return call(function* () {
+        const postman = new Poster(hby, null, null, http, clock);
+        yield* resource(function* (provide) {
+            try {
+                yield* provide();
+            }
+            finally {
+                yield* postman.close();
+            }
+        });
+        const dest = new Organizer(hby.db, hby.signator).resolveRecipient(args.dest);
+        const topic = args.topic ?? mailboxTopicForRoute(args.route);
+        if (!topic)
+            throw new ValidationError(`Unable to derive mailbox topic from route ${args.route}.`);
+        const { serder, msg } = createExchangeMessage(hab, { ...args, dest });
+        yield* spawn(() => postman.deliverDo());
+        const evt = postman.send({ src: hab.pre, dest, topic, msg }, { notify: true });
+        const outcome = yield* postman.wait(evt);
+        if (outcome.kin === "failed")
+            throw outcome.error;
+        return { serder, deliveries: outcome.deliveries };
+    });
+}