keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/app/witness/receipting.js

@@ -0,0 +1,323 @@
+/** Collect accepted historical witness receipts and fan them out before reporting event completion. */
+import { collectPayload, concatBytes, Counter, framePayload, Ilks, parseBytes, Vrsn_1_0, } from "cesr-ts";
+import { call } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { receipt as receiptEvent } from "../../core/protocol-eventing.js";
+import { messagize } from "../../core/protocol-serialization.js";
+import { dgKey } from "../../db/core/keys.js";
+import { acceptedEventReplayMessage } from "../identity/habbing.js";
+import { chunkBytes } from "../transport/byte-source.js";
+import { processMessages } from "../transport/message-source.js";
+import { getWitnessReceiptEndpoint, pollWitnessReceipt, postWitnessReceiptEndpoint, sendWitnessMessage, witnessHttpUrl, witnessTcpUrl, } from "./receipt-client.js";
+import { buildDetachedReceiptMessage } from "./receipt-messages.js";
+/** Build one `loc/scheme` replay bundle for witness introductions. */
+function* witnessSchemeReplies(hab, eids, gvrsn) {
+    const replies = eids
+        .map((eid) => hab.loadLocScheme(eid))
+        .filter((msg) => msg.length > 0);
+    const raw = concatBytes(...replies);
+    if (!raw.length || gvrsn.major === 1)
+        return raw;
+    const messages = yield* call(() => Promise.all(parseBytes(raw).map(frame => collectPayload(framePayload(frame, { gvrsn })))));
+    return concatBytes(...messages);
+}
+/**
+ * Controller-side synchronous witness receipt orchestration.
+ *
+ * Responsibilities:
+ * - publish through HTTP receipt endpoints (generic submission opts into TCP reply intake)
+ * - catch up newly added witnesses before receipting
+ * - persist returned receipts locally through the protocol processor
+ * - fan witness receipts out to the complementary witnesses
+ */
+export class Receiptor {
+    /**
+     * Bind configured intake over the same Habery; acquire no stores or background workers.
+     *
+     * @param hby Borrowed local identities and accepted-state stores.
+     * @param protocol Borrowed same-database protocol owner for receipt intake.
+     * @param http Borrowed HTTP implementation selected by composition.
+     * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+     * @param options Explicit witness attachment genus; the historical v1 default is independent of KEL body version.
+     */
+    constructor(hby, protocol, http, clock, { gvrsn = Vrsn_1_0 } = {}) {
+        /** Borrowed accepted state and local signer collection. */
+        Object.defineProperty(this, "hby", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Shared receipt verification, cue publication and escrow processing. */
+        Object.defineProperty(this, "protocol", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Input-owned Kevery (kvy) for request-owned receipt GET/POST evidence. */
+        Object.defineProperty(this, "kvy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Borrowed HTTP and clock services used by actual receipt operations. */
+        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
+        });
+        /** Explicit attachment framing for the configured witness endpoints; independent of KEL body version. */
+        Object.defineProperty(this, "gvrsn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const kvy = protocol.makeKevery();
+        if (kvy.db !== hby.db)
+            throw new RangeError("Receiptor protocol must use the same database");
+        this.hby = hby;
+        this.protocol = protocol;
+        this.kvy = kvy;
+        this.http = http;
+        this.clock = clock;
+        this.gvrsn = gvrsn;
+    }
+    /** Submit the latest or specified event to all witnesses and gather receipts. */
+    *receipt(pre, { sn, auths = {}, allowTcp = false } = {}) {
+        return yield* call(() => this.receiptOnce(pre, { sn, auths }, allowTcp));
+    }
+    /**
+     * One scoped attempt joins actual receipt HTTP/TCP work before returning.
+     *
+     * @param pre Local event subject AID.
+     * @param options Optional event sequence and witness Authorization map.
+     * @param allowTcp Whether missing HTTP receipt routes may use TCP message delivery.
+     * @returns Receipt-attempt result based on verified local witness proof.
+     */
+    *receiptOnce(pre, { sn, auths }, allowTcp) {
+        const hab = this.hby.habs.get(pre) ?? null;
+        if (!hab) {
+            throw new ValidationError(`${pre} not a valid local AID.`);
+        }
+        const kever = hab.kever;
+        if (!kever) {
+            throw new ValidationError(`Missing accepted key state for ${pre}.`);
+        }
+        const eventSn = sn ?? kever.sn;
+        const { serder, message } = acceptedEventReplayMessage(this.hby, pre, eventSn, this.gvrsn);
+        const witnesses = this.hby.db.acceptedEventWitnesses(serder);
+        if (witnesses.length === 0) {
+            return { witnesses: [], statuses: {} };
+        }
+        if (serder.ilk === Ilks.rot || serder.ilk === Ilks.drt) {
+            for (const witness of serder.adds) {
+                yield* this.catchup(pre, witness);
+            }
+        }
+        const receiptGroups = new Map();
+        const statuses = {};
+        const said = serder.said;
+        if (!said) {
+            throw new ValidationError("Local event must expose a SAID before witness receipting.");
+        }
+        for (const witness of witnesses) {
+            if (kever.delegated) {
+                for (const dmsg of this.hby.db.cloneDelegation(kever, this.gvrsn)) {
+                    yield* sendWitnessMessage(hab, witness, this.selected(dmsg), this.http, this.clock, this.protocol);
+                }
+            }
+            if (allowTcp && !witnessHttpUrl(hab, witness) && witnessTcpUrl(hab, witness)) {
+                yield* sendWitnessMessage(hab, witness, this.selected(message), this.http, this.clock, this.protocol);
+                statuses[witness] = 200;
+            }
+            else {
+                // A single receipt attempt owns its response until parsing and collection finish.
+                let response = yield* call(() => postWitnessReceiptEndpoint(hab, witness, message, this.http, auths[witness], this.gvrsn));
+                if (response.kind === "escrow") {
+                    response = yield* pollWitnessReceipt(hab, witness, pre, eventSn, said, this.http, this.gvrsn);
+                }
+                statuses[witness] = response.status;
+                if (response.kind !== "accepted") {
+                    const detail = response.kind === "reject" ? response.message : "receipt remained escrowed";
+                    throw new ValidationError(`Witness ${witness} failed to receipt ${pre}:${eventSn.toString(16)}: ${detail}`);
+                }
+                yield* processMessages((signal) => chunkBytes(response.body, { signal }), this.protocol, this.kvy, {
+                    local: false,
+                });
+                yield* this.protocol.processEscrowsOnce();
+            }
+            // HTTP status and socket drain are transport facts; only accepted witness proof counts.
+            const index = witnesses.indexOf(witness);
+            const wigers = this.hby.db.wigs.get(dgKey(pre, said)).filter((siger) => siger.index === index);
+            if (wigers.length === 0) {
+                throw new ValidationError(`Witness ${witness} did not receipt ${pre}:${eventSn.toString(16)}.`);
+            }
+            receiptGroups.set(witness, wigers);
+        }
+        for (const witness of witnesses) {
+            const otherWigers = [...receiptGroups.entries()]
+                .flatMap(([current, wigers]) => current === witness ? [] : [...wigers]);
+            if (otherWigers.length === 0) {
+                continue;
+            }
+            const introWitnesses = witnesses.filter((current) => current !== witness && receiptGroups.has(current));
+            const parts = [];
+            if (serder.ilk === Ilks.icp
+                || serder.ilk === Ilks.dip
+                || ((serder.ilk === Ilks.rot || serder.ilk === Ilks.drt)
+                    && serder.adds.includes(witness))) {
+                const schemes = yield* witnessSchemeReplies(hab, introWitnesses, this.gvrsn);
+                if (schemes.length > 0) {
+                    parts.push(schemes);
+                }
+            }
+            parts.push(this.gvrsn.major === 1
+                ? buildDetachedReceiptMessage(receiptEvent(pre, eventSn, said, { pvrsn: serder.pvrsn, gvrsn: serder.pvrsn }), { wigers: otherWigers })
+                : messagize(receiptEvent(pre, eventSn, said, { pvrsn: serder.pvrsn, gvrsn: serder.pvrsn }), {
+                    wigers: otherWigers,
+                    gvrsn: this.gvrsn,
+                    pipelined: true,
+                    genusify: true,
+                }));
+            yield* sendWitnessMessage(hab, witness, concatBytes(...parts), this.http, this.clock, this.protocol);
+        }
+        return { witnesses, statuses };
+    }
+    /**
+     * Query a stored witness receipt and apply it to local state when found.
+     *
+     * @param pre Event subject AID.
+     * @param options Optional sequence/SAID selection; defaults follow current accepted state.
+     * @returns Whether matching verified witness receipt state was obtained.
+     */
+    *get(pre, { sn, said } = {}) {
+        const hab = this.hby.habs.get(pre) ?? null;
+        if (!hab) {
+            throw new ValidationError(`${pre} not a valid local AID.`);
+        }
+        const kever = hab.kever;
+        if (!kever) {
+            throw new ValidationError(`Missing accepted key state for ${pre}.`);
+        }
+        const eventSn = sn ?? kever.sn;
+        const knownSaid = this.hby.db.kels.getLast(pre, eventSn);
+        const known = knownSaid ? this.hby.db.getEvtSerder(pre, knownSaid) : null;
+        const witnesses = known ? this.hby.db.acceptedEventWitnesses(known) : kever.wits;
+        const witness = [...witnesses].sort()[0];
+        if (!witness) {
+            return false;
+        }
+        const response = yield* call(() => getWitnessReceiptEndpoint(hab, witness, { pre, sn: eventSn, said }, this.http, this.gvrsn));
+        if (response.kind !== "accepted") {
+            return false;
+        }
+        yield* processMessages((signal) => chunkBytes(response.body, { signal }), this.protocol, this.kvy, {
+            local: false,
+        });
+        yield* this.protocol.processEscrowsOnce();
+        const expectedSaid = this.hby.db.kels.getLast(pre, eventSn);
+        const accepted = expectedSaid ? this.hby.db.getEvtSerder(pre, expectedSaid) : null;
+        const index = accepted ? this.hby.db.acceptedEventWitnesses(accepted)?.indexOf(witness) : -1;
+        return !!expectedSaid && (said === undefined || said === expectedSaid)
+            && this.hby.db.wigs.get(dgKey(pre, expectedSaid)).some((siger) => siger.index === index);
+    }
+    /**
+     * Catch one witness up through the same protocol processor used for receipt intake.
+     *
+     * @param pre Local KEL subject to replay.
+     * @param witness Witness AID to catch up.
+     */
+    *catchup(pre, witness) {
+        const hab = this.hby.habs.get(pre) ?? null;
+        if (!hab) {
+            throw new ValidationError(`${pre} not a valid local AID.`);
+        }
+        const kever = hab.kever;
+        if (kever?.delegated) {
+            for (const msg of this.hby.db.cloneDelegation(kever, this.gvrsn)) {
+                yield* sendWitnessMessage(hab, witness, this.selected(msg), this.http, this.clock, this.protocol);
+            }
+        }
+        for (const msg of this.hby.db.clonePreIter(pre, 0, this.gvrsn)) {
+            yield* sendWitnessMessage(hab, witness, this.selected(msg), this.http, this.clock, this.protocol);
+        }
+    }
+    /** Complete streams select their framing before the body; detached receipt headers retain their existing enclosure. */
+    selected(message) {
+        return this.gvrsn.major === 1 ? message : concatBytes(Counter.makeGVC(this.gvrsn), message);
+    }
+}
+/**
+ * Higher-level full witness submission helper.
+ *
+ * HTTP uses finite receipt endpoints; TCP uses same-socket local reply intake
+ * and requires the requested witness signature to be persisted before fanout.
+ */
+export class WitnessReceiptor {
+    /**
+     * Bind actual protocol/I/O dependencies; only the scalar force choice is optional.
+     *
+     * @param hby Borrowed local identities and accepted-state stores.
+     * @param protocol Borrowed same-database protocol owner for receipt intake.
+     * @param http Borrowed HTTP implementation selected by composition.
+     * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+     * @param options force defaults false; true requests the existing forced witness submission policy.
+     */
+    constructor(hby, protocol, http, clock, { force = false } = {}) {
+        /** Actual receipt-intake/fanout owner over the same shared protocol domain. */
+        Object.defineProperty(this, "receiptor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Borrowed identities and accepted witness cohorts. */
+        Object.defineProperty(this, "hby", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Existing explicit request to publish even when cached receipt completion is available. */
+        Object.defineProperty(this, "force", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.hby = hby;
+        this.force = force;
+        this.receiptor = new Receiptor(hby, protocol, http, clock);
+    }
+    /** Ensure the current event reaches full witness receipt convergence. */
+    *submit(pre, { sn, auths = {} } = {}) {
+        const hab = this.hby.habs.get(pre) ?? null;
+        if (!hab) {
+            throw new ValidationError(`${pre} not a valid local AID.`);
+        }
+        const kever = hab.kever;
+        if (!kever) {
+            throw new ValidationError(`Missing accepted key state for ${pre}.`);
+        }
+        const eventSn = sn ?? kever.sn;
+        const { serder } = acceptedEventReplayMessage(this.hby, pre, eventSn);
+        const witnesses = this.hby.db.acceptedEventWitnesses(serder);
+        const currentWitnessCount = this.hby.db.wigs.get(dgKey(pre, serder.said)).length;
+        if (!this.force && currentWitnessCount >= witnesses.length) {
+            const statuses = Object.fromEntries(witnesses.map((witness) => [witness, 200]));
+            return { witnesses, statuses };
+        }
+        return yield* this.receiptor.receipt(pre, { sn: eventSn, auths, allowTcp: true });
+    }
+}

package/esm/keri/npm/src/app/witness/registration.js

@@ -0,0 +1,50 @@
+/** Controller-side witness TOTP registration over the witness-hk `POST /aids` contract. */
+import { concatBytes, Matter } from "cesr-ts";
+import { call } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { CESR_DESTINATION_HEADER } from "../transport/cesr-http.js";
+/**
+ * Register `hab` with one witness and return the plaintext TOTP secret.
+ *
+ * Locksmith correspondence: `register_with_witness`. The controller's full KEL
+ * (and, when delegated, its delegation chain as `delkel`) and an optional batch
+ * `secret` go as multipart text fields with `CESR-DESTINATION`; the returned
+ * `totp` ciphertext is opened with the habitat's current keys (`Hab.decrypt`).
+ * Because the full KEL is sent, registration works at any key state. Nothing
+ * is persisted here: retaining or displaying the secret is the caller's choice.
+ */
+export function* registerWithWitness(hab, witness, http, { secret } = {}) {
+    const kever = hab.kever;
+    if (!kever)
+        throw new ValidationError(`Missing accepted key state for ${hab.pre}.`);
+    const genus = kever.serder.pvrsn, text = new TextDecoder();
+    const form = new FormData();
+    form.set("kel", text.decode(concatBytes(...hab.db.clonePreIter(hab.pre, 0, genus))));
+    if (secret !== undefined)
+        form.set("secret", secret);
+    if (kever.delegated)
+        form.set("delkel", text.decode(concatBytes(...hab.db.cloneDelegation(kever, genus))));
+    const encoded = new Response(form);
+    const body = new Uint8Array(yield* call(() => encoded.arrayBuffer()));
+    const response = yield* http.request(new URL("/aids", witness.url).href, {
+        method: "POST",
+        redirect: "error",
+        headers: { "Content-Type": encoded.headers.get("Content-Type"), [CESR_DESTINATION_HEADER]: witness.eid },
+        body,
+    });
+    if (!response.ok)
+        throw new ValidationError(`Witness registration failed with HTTP ${response.status}.`);
+    const data = JSON.parse(text.decode(response.body));
+    if (typeof data?.totp !== "string")
+        throw new ValidationError("Witness registration response lacks totp.");
+    const plain = hab.decrypt(data.totp);
+    try {
+        return {
+            secret: text.decode(new Matter({ qb64b: plain }).raw),
+            oobi: typeof data.oobi === "string" ? data.oobi : "",
+        };
+    }
+    finally {
+        plain.fill(0);
+    }
+}

package/esm/keri/npm/src/cli/common/bootstrap.js

@@ -0,0 +1,12 @@
+import { ValidationError } from "../../core/errors.js";
+/** Refuse unsuccessful bootstrap before command effects or success output continue. */
+export function assertBootstrapComplete(result) {
+    switch (result.kind) {
+        case "complete":
+            return;
+        case "failed":
+            throw new ValidationError(`Bootstrap failed: ${result.failures.map(({ url, state }) => `${url} (${state})`).join(", ")}`);
+        case "timeout":
+            throw new ValidationError(`Bootstrap deadline reached with pending evidence: ${result.pending.join(", ")}`);
+    }
+}

package/esm/keri/npm/src/{app/cli → cli}/common/context.js

@@ -1,5 +1,7 @@
-import { ValidationError } from "../../../core/errors.js";
-import { createAgentRuntime } from "../../agent-runtime.js";
+import { createAgentRuntime } from "../../app/runtime/agent-runtime.js";
+import { systemClock } from "../../app/runtime/runtime-clock.js";
+import { FetchHttpClient } from "../../app/transport/http-client.js";
+import { ValidationError } from "../../core/errors.js";
 import { setupHby } from "./existing.js";
 /** Open an existing Habery for one CLI command and close it after the callback. */
 export function* withExistingHabery(args, options, use) {
@@ -9,11 +11,26 @@ export function* withExistingHabery(args, options, use) {
         ...openOptions,
         compat: options.compat ?? args.compat ?? false,
     });
+    let failure;
     try {
         return yield* use({ hby });
     }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
     finally {
-        yield* hby.close();
+        try {
+            yield* hby.close();
+        }
+        catch (error) {
+            if (failure) {
+                // deno-lint-ignore no-unsafe-finally -- Preserve the operation failure alongside shutdown failure.
+                throw new AggregateError([failure.error, error], "Command and database close failed", { cause: failure.error });
+            }
+            // deno-lint-ignore no-unsafe-finally -- A shutdown failure must propagate.
+            throw error;
+        }
     }
 }
 /** Open an existing Habery and required local habitat alias for one CLI command. */
@@ -27,15 +44,39 @@ export function* withExistingHab(args, alias, options, use) {
         return yield* use({ hby, hab });
     });
 }
-/** Open an existing Habery plus local AgentRuntime and close runtime before Habery. */
+/**
+ * Open an existing Habery plus local AgentRuntime and close runtime before Habery.
+ *
+ * @param args Command store identity, path and unlocking inputs.
+ * @param options Habery open/policy choices forwarded by the command root.
+ * @param use Awaited callback borrowing the opened Habery/runtime; start required workers inside its scope.
+ * @returns Callback result after runtime closes before Habery.
+ */
 export function* withAgentRuntime(args, options, use) {
     return yield* withExistingHabery(args, options, function* ({ hby }) {
-        const runtime = yield* (options.dependencies?.createAgentRuntime ?? createAgentRuntime)(hby);
+        const runtime = yield* (options.dependencies?.createAgentRuntime ?? createAgentRuntime)(hby, new FetchHttpClient(), systemClock, { kram: hby.cf?.get().kram });
+        let failure;
         try {
             return yield* use({ hby, runtime });
         }
+        catch (error) {
+            failure = { error };
+            throw error;
+        }
         finally {
-            yield* runtime.close();
+            try {
+                yield* runtime.close();
+            }
+            catch (error) {
+                if (failure) {
+                    // deno-lint-ignore no-unsafe-finally -- Preserve the operation failure alongside shutdown failure.
+                    throw new AggregateError([failure.error, error], "Command and runtime close failed", {
+                        cause: failure.error,
+                    });
+                }
+                // deno-lint-ignore no-unsafe-finally -- A shutdown failure must propagate.
+                throw error;
+            }
         }
     });
 }

package/esm/keri/npm/src/{app/cli → cli}/common/existing.js

@@ -1,6 +1,7 @@
-import { createKeeper, Keeper } from "../../../db/keeping.js";
-import { cesrBodyModeFromGlobal, normalizeCesrBodyMode } from "../../cesr-http.js";
-import { createHabery } from "../../habbing.js";
+import * as dntShim from "../../_dnt.shims.js";
+import { createHabery } from "../../app/identity/habbing.js";
+import { createKeeper, Keeper } from "../../db/keeping.js";
+import { readPasscode } from "./passcode.js";
 /**
  * Return true when the named keeper already exists and contains keeper globals.
  *
@@ -50,12 +51,10 @@ export function* setupHby(name, base = "", bran, temp = false, headDirPath, opti
         readonly: true,
     });
     const aeid = ks.getGbls("aeid");
-    const storedCesrBodyMode = cesrBodyModeFromGlobal(ks.getGbls("cesrBodyMode"));
     yield* ks.close();
     if (aeid === null) {
         throw new Error("Keystore must already exist, exiting");
     }
-    const cesrBodyMode = normalizeCesrBodyMode(options.cesrBodyMode, storedCesrBodyMode);
     let retries = 0;
     let passcode = bran;
     while (true) {
@@ -72,19 +71,20 @@ export function* setupHby(name, base = "", bran, temp = false, headDirPath, opti
                 skipConfig: options.skipConfig,
                 skipSignator: options.skipSignator,
                 bran: passcode?.replaceAll("-", ""),
-                cesrBodyMode,
             });
         }
         catch (error) {
+            if (!dntShim.Deno.stdin.isTerminal())
+                throw error;
             if (retries >= 3) {
                 throw new Error("too many attempts");
             }
             const message = error instanceof Error ? error.message : String(error);
-            console.log(message);
-            console.log("Valid passcode required, try again...");
+            console.error(message);
+            console.error("Valid passcode required, try again...");
             // Match the long-standing CLI operator contract: retry interactively
             // instead of failing immediately on the first decrypt/auth attempt.
-            passcode = prompt("Passcode: ") ?? undefined;
+            passcode = yield* readPasscode("Passcode:");
         }
     }
 }
@@ -114,8 +114,6 @@ export function* ensureHby(name, base = "", bran, temp = false, headDirPath, opt
         skipConfig: options.skipConfig,
         skipSignator: options.skipSignator,
         bran: bran?.replaceAll("-", ""),
-        cesrBodyMode: normalizeCesrBodyMode(options.cesrBodyMode),
     });
-    hby.ks.pinGbls("cesrBodyMode", normalizeCesrBodyMode(options.cesrBodyMode));
     return { hby, created: true };
 }