keri-ts 2.1.0 → 2.2.0

package/esm/keri/npm/src/app/multisig/counseling.js

@@ -0,0 +1,482 @@
+/**
+ * Group-event Counselor: drives an accepted-or-pending group KEL event through
+ * member signatures and witness receipts, as KERIpy `app.grouping.Counselor`.
+ *
+ * Durable state is KERIpy's, row for row: `gpse` and `gpwe` hold `(pre) ->
+ * IoSet[(Number, Diger)]`, `gdee` holds delegated events awaiting the delegator
+ * and `cgms` holds `(pre, number.qb64) -> Diger` for completed events. The
+ * Counselor never signs; it only observes accepted state and, for witness
+ * receipts, asks the injected receipting collaborator to submit or fetch.
+ *
+ * Divergences from KERIpy, each deliberate:
+ * - An escrow row is removed by exact `(Number, Diger)` tuple. KERIpy removes
+ *   every row of the prefix and never compares digests; here a different SAID
+ *   accepted at the same sn drops only the stale tuple and reads `superseded`.
+ * - Receipts are judged against the event's own governing establishment, not
+ *   the prefix's current key state.
+ * - "Must submit" derives from stored receipts and the election, not from an
+ *   in-memory cue, so a restarted process resumes. Non-elected members fetch
+ *   receipts and, after `fallbackAfterMs`, submit as the elected one would;
+ *   KERIpy stalls when the elected member is offline.
+ * - A newer completion at the same `(pre, sn)` replaces the `cgms` digest.
+ * - A delegated `dip`/`drt` is accepted by its own delegate before the delegator's
+ *   anchor and before witnesses receipt it (KERIpy `validateDelegation`: the
+ *   delegatee accepts its own event to trigger receipting and approval). It
+ *   waits in `gdee`. The publishing member (elected, or any member once the
+ *   fallback grace passes) hands it to the Anchorer, which requests approval,
+ *   awaits the anchor and publishes; the Counselor gates and observes, and
+ *   writes `cgms` when the Anchorer completes. Any other member queries the
+ *   delegator's witness for the anchor, pins `aess`, and continues in `gpwe`.
+ *   Without an Anchorer such events stay in `gdee`, reported `notSupported`.
+ *
+ * Witness authorization codes, the delegation proxy and retry timers are process
+ * memory only, as in KERIpy and the Anchorer. Without a proxy the local group
+ * member sends delegation traffic, as KERIpy does for every group event, so a
+ * restart never leaves a delegated event waiting for one. Collaborators are
+ * narrow (ADR-0013); nothing here reaches a runtime.
+ */
+import { Diger, Ilks, NumberPrimitive, NumDex, Verfer } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
+import { Kever } from "../../core/kel/kever.js";
+import { dgKey } from "../../db/core/keys.js";
+import { pinAuthorizingSeal, retryDelegatorWitnessQuery, } from "../identity/delegating.js";
+import { observeUntil } from "../runtime/workflow-contract.js";
+import { groupWitnesser, isLocalGroupHab, localGroupMember } from "./group-members.js";
+/** Grace before a non-elected member submits receipts itself. */
+export const DEFAULT_FALLBACK_AFTER_MS = 60_000;
+/** First and longest wait between receipt attempts for one event. */
+export const RECEIPT_BACKOFF_MS = { first: 1_000, max: 30_000 };
+/** The production receipt retry delays as a policy; only `baseMs` and `maxMs` apply, the Counselor never gives up. */
+export const DEFAULT_RECEIPT_RETRY = Object.freeze({
+    baseMs: RECEIPT_BACKOFF_MS.first,
+    maxMs: RECEIPT_BACKOFF_MS.max,
+    boundMs: 0,
+});
+/** Escrow tables in stage order. */
+const STAGES = [["signatures", "gpse"], ["delegation", "gdee"], ["witnesses", "gpwe"]];
+/** Receipt progress of one event against its own governing establishment. */
+function receiptProgress(db, serder) {
+    let est = serder;
+    while (est && !est.estive)
+        est = est.prior ? db.getEvtSerder(est.pre, est.prior) : null;
+    if (!est)
+        return { have: 0, need: 0, missing: [] };
+    const witnesses = db.wits.get(dgKey(est.pre, est.said)).map(wit => wit.qb64);
+    const { indices } = Kever.verifyIndexedSignatures(serder.raw, db.wigs.get(dgKey(serder.pre, serder.said)), witnesses.map(qb64 => new Verfer({ qb64 })));
+    return {
+        have: indices.length,
+        need: Number(est.bner.num),
+        missing: witnesses.filter((_, index) => !indices.includes(index)),
+    };
+}
+/** Counsels group events through signature and witness stages. */
+export class Counselor {
+    /**
+     * @param hby Borrowed identities and stores; the Counselor opens nothing.
+     * @param receipting Submits or fetches witness receipts for accepted events.
+     * @param clock Time source for fallback and retry; only `now` is used.
+     * @param changes Optional sink told `{kind:"group", id:"<pre>:<sn>"}` after commits.
+     * @param delegation Anchorer and query port for delegated events; omit for non-delegated hosts.
+     * @param mailboxes Told when one of the group's rotations completes; the member runtime's publisher then tells
+     *   the group's mailboxes the new key state, and several members doing so is harmless.
+     */
+    constructor(hby, receipting, clock, changes, delegation, mailboxes, receiptRetry = DEFAULT_RECEIPT_RETRY) {
+        Object.defineProperty(this, "hby", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: hby
+        });
+        Object.defineProperty(this, "receipting", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: receipting
+        });
+        Object.defineProperty(this, "clock", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: clock
+        });
+        Object.defineProperty(this, "changes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: changes
+        });
+        Object.defineProperty(this, "delegation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: delegation
+        });
+        Object.defineProperty(this, "mailboxes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: mailboxes
+        });
+        Object.defineProperty(this, "receiptRetry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: receiptRetry
+        });
+        Object.defineProperty(this, "runs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "anchorQuery", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.anchorQuery = delegation && { hby, querying: delegation.querying, retryPasses: new Map() };
+    }
+    /**
+     * Begin counseling an event. Idempotent and safe before local acceptance.
+     *
+     * @returns True when a new `gpse` row was added; false when the event is
+     *   already counseled or complete, or another SAID holds that sn.
+     * @throws ValidationError when `pre` is not a local group or the ref is malformed.
+     */
+    start(event, inputs = {}) {
+        const { pre, sn, said } = event;
+        if (!Number.isSafeInteger(sn) || sn < 0 || !said)
+            throw new ValidationError("Invalid group event reference.");
+        const hab = this.hby.habs.get(pre);
+        if (!hab || !isLocalGroupHab(this.hby, hab))
+            throw new ValidationError(`${pre} is not a local group.`);
+        const db = this.hby.db;
+        if (this.settled(event))
+            return false; // nothing to counsel, so nothing to retain
+        this.retain(event, inputs);
+        if (this.stageOf(event))
+            return false;
+        return db.gpse.add([pre], [NumberPrimitive.fromNum(BigInt(sn)), new Diger({ qb64: said })]);
+    }
+    /**
+     * Replace in-memory inputs of a counseled event, for example witness auths or
+     * a proxy after a restart, and re-arm any attempt waiting out its backoff.
+     * Ignored for an event that is already complete or superseded.
+     */
+    supply(event, inputs) {
+        if (!this.settled(event))
+            this.retain(event, inputs);
+    }
+    /** Pure read of one event's state. */
+    status(event) {
+        const { pre, sn, said } = event;
+        const done = this.completed(pre, sn);
+        if (done !== null)
+            return done === said ? { state: "complete" } : { state: "superseded", accepted: done };
+        const accepted = this.hby.db.kels.getLast(pre, sn);
+        if (accepted && accepted !== said)
+            return { state: "superseded", accepted };
+        const stage = this.stageOf(event);
+        if (!stage)
+            return { state: "unknown" };
+        // A counseled event may not be stored locally yet; it is still pending, not unknown.
+        const serder = this.hby.db.getEvtSerder(pre, said);
+        if (!serder)
+            return { state: "pending", stage, elected: null, receipts: { have: 0, need: 0 } };
+        const { have, need, missing } = receiptProgress(this.hby.db, serder);
+        const elected = accepted ? groupWitnesser(this.hby, pre, { sn, said }) : null;
+        const status = { state: "pending", stage, elected, receipts: { have, need } };
+        const run = this.runs.get(this.runKey(event));
+        const failure = run?.failure ? this.receiptBlock(run, missing) : undefined;
+        if (stage === "delegation")
+            status.blocked = this.delegationBlock(event) ?? failure;
+        else if (stage === "witnesses")
+            status.blocked = failure;
+        if (!status.blocked)
+            delete status.blocked;
+        return status;
+    }
+    /** Why a receipt attempt failed: missing auths for unreceipted witnesses, else the witness's own reason. */
+    receiptBlock(run, missing) {
+        const unauthorized = missing.filter(witness => !(witness in run.auths));
+        return unauthorized.length
+            ? { kind: "witnessAuth", witnesses: unauthorized }
+            : { kind: "witness", reason: run.failure };
+    }
+    /** What keeps a delegated event in `gdee`, if anything the caller can fix. */
+    delegationBlock(event) {
+        if (!this.delegation)
+            return { kind: "notSupported", feature: "delegation" };
+        const delpre = this.hby.db.getKever(event.pre)?.delpre;
+        if (delpre && !this.hby.db.getKever(delpre))
+            return { kind: "delegatorUnknown", delpre };
+        return undefined;
+    }
+    fallbackElapsed(run) {
+        return !!run && run.since !== null && this.clock.now() - run.since >= run.fallbackAfterMs;
+    }
+    /** True when the event is complete, or another SAID holds its sn. */
+    settled({ pre, sn, said }) {
+        const accepted = this.hby.db.kels.getLast(pre, sn);
+        return (!!accepted && accepted !== said) || this.completed(pre, sn) !== null;
+    }
+    /** Events still counseled for `pre`, or for every prefix, in stage order. */
+    pending(pre) {
+        const found = [];
+        for (const [stage, table] of STAGES) {
+            for (const [[key], [number, diger]] of this.hby.db[table].getTopItemIter(pre ?? "", { topive: !!pre })) {
+                found.push({ pre: key, sn: Number(number.num), said: diger.qb64, stage });
+            }
+        }
+        return found;
+    }
+    /** True once the exact event completed; drops its in-memory inputs. */
+    complete(event) {
+        const done = this.completed(event.pre, event.sn) === event.said;
+        if (done)
+            this.runs.delete(this.runKey(event));
+        return done;
+    }
+    /**
+     * Stop counseling `pre`: remove its escrow rows, completion markers and
+     * in-memory inputs. Accepted KEL state is untouched.
+     */
+    abandon(pre) {
+        const db = this.hby.db;
+        const removed = new Set(this.pending(pre).map(event => event.sn));
+        for (const [[, number]] of db.cgms.getTopItemIter([pre], { topive: true })) {
+            removed.add(Number(new NumberPrimitive({ qb64: number }).num));
+        }
+        db.transaction(() => {
+            for (const [, table] of STAGES)
+                db[table].rem([pre]);
+            for (const [keys] of [...db.cgms.getTopItemIter([pre], { topive: true })])
+                db.cgms.rem(keys);
+        });
+        for (const key of [...this.runs.keys()])
+            if (key.startsWith(`${pre}:`))
+                this.runs.delete(key);
+        for (const sn of removed)
+            this.changes?.push({ kind: "group", id: `${pre}:${sn}` });
+    }
+    /** One pass over all stages, as KERIpy `processEscrows`. */
+    *processOnce() {
+        // A runtime calls this every turn; with nothing counseled, three row counts are the whole cost.
+        const db = this.hby.db;
+        if (db.gpse.cnt() === 0 && db.gdee.cnt() === 0 && db.gpwe.cnt() === 0)
+            return;
+        this.processSignatures();
+        yield* this.processDelegation();
+        yield* this.processWitnesses();
+    }
+    /** Move events accepted with their escrowed SAID on to delegation or witnesses. */
+    processSignatures() {
+        for (const [[pre], [number, diger]] of [...this.hby.db.gpse.getTopItemIter()]) {
+            const event = this.refOf(pre, number, diger);
+            if (this.dropIfSuperseded(this.hby.db.gpse, event, number, diger))
+                continue;
+            if (this.hby.db.kels.getLast(pre, event.sn) !== event.said)
+                continue;
+            const ilk = this.hby.db.getEvtSerder(pre, event.said)?.ilk;
+            const next = ilk === Ilks.dip || ilk === Ilks.drt ? this.hby.db.gdee : this.hby.db.gpwe;
+            this.hby.db.transaction(() => {
+                this.hby.db.gpse.rem([pre], [number, diger]);
+                next.add([pre], [number, diger]);
+            });
+            this.changes?.push({ kind: "group", id: `${pre}:${event.sn}` });
+        }
+    }
+    /**
+     * Delegated events: the publishing member drives the Anchorer, any other member
+     * watches for the delegator's anchor. Both wait for the delegator's KEL.
+     */
+    *processDelegation() {
+        const db = this.hby.db;
+        for (const [[pre], [number, diger]] of [...db.gdee.getTopItemIter()]) {
+            const event = this.refOf(pre, number, diger);
+            if (this.dropIfSuperseded(db.gdee, event, number, diger))
+                continue;
+            const serder = db.getEvtSerder(pre, event.said);
+            const delpre = db.getKever(pre)?.delpre;
+            if (!this.delegation || !serder || !delpre || !db.getKever(delpre))
+                continue;
+            const run = this.retain(event, {});
+            run.since ??= this.clock.now();
+            const member = localGroupMember(this.hby, pre);
+            if (groupWitnesser(this.hby, pre, event) || this.fallbackElapsed(run)) {
+                yield* this.publishDelegation(event, serder, run, member, [number, diger]);
+            }
+            else {
+                this.watchAnchor(event, serder, run, member, delpre, [number, diger]);
+            }
+        }
+    }
+    /** Publishing duty: begin the Anchorer, keep receipts coming, and record completion. */
+    *publishDelegation(event, serder, run, member, row) {
+        const { anchorer } = this.delegation;
+        if (anchorer.complete(event.pre, event.sn)) {
+            this.finish(this.hby.db.gdee, event, row);
+            return;
+        }
+        // The Anchorer asks the delegator only once the event's witnesses have receipted it.
+        if (!this.hby.db.fullyWitnessed(serder))
+            yield* this.pursueReceipts(event, serder, true);
+        if (!run.begun) {
+            anchorer.begin(serder, { communicationHab: run.proxy ?? member });
+            run.begun = true;
+            this.changes?.push({ kind: "group", id: `${event.pre}:${event.sn}` });
+        }
+    }
+    /** Non-publishing duty: find the delegator's sealing event, pin it, and move on to receipts. */
+    watchAnchor(event, serder, run, member, delpre, row) {
+        const db = this.hby.db;
+        retryDelegatorWitnessQuery(this.anchorQuery, serder, run.proxy ?? member);
+        const delegating = db.fetchLastSealingEventByEventSeal(delpre, { i: event.pre, s: serder.snh, d: event.said });
+        if (!delegating)
+            return;
+        pinAuthorizingSeal(this.hby, serder, delegating);
+        db.transaction(() => {
+            db.gdee.rem([event.pre], row);
+            db.gpwe.add([event.pre], row);
+        });
+        this.changes?.push({ kind: "group", id: `${event.pre}:${event.sn}` });
+    }
+    /** Record completion of a counseled event and drop its row from `table`. */
+    finish(table, event, row) {
+        const db = this.hby.db;
+        db.transaction(() => {
+            table.rem([event.pre], row);
+            db.cgms.pin([event.pre, row[0].qb64], row[1]);
+        });
+        this.runs.delete(this.runKey(event));
+        this.changes?.push({ kind: "group", id: `${event.pre}:${event.sn}` });
+        const ilk = db.getEvtSerder(event.pre, event.said)?.ilk;
+        if (ilk === Ilks.rot || ilk === Ilks.drt) {
+            this.mailboxes?.rotated({ kin: "rotated", pre: event.pre, sn: event.sn, said: event.said });
+        }
+    }
+    /** Complete events whose own witness threshold is met; otherwise submit or fetch receipts. */
+    *processWitnesses() {
+        const db = this.hby.db;
+        for (const [[pre], [number, diger]] of [...db.gpwe.getTopItemIter()]) {
+            const event = this.refOf(pre, number, diger);
+            if (this.dropIfSuperseded(db.gpwe, event, number, diger))
+                continue;
+            const serder = db.getEvtSerder(pre, event.said);
+            if (!serder)
+                continue;
+            if (!db.fullyWitnessed(serder)) {
+                yield* this.pursueReceipts(event, serder);
+                if (!db.fullyWitnessed(serder))
+                    continue;
+            }
+            this.finish(db.gpwe, event, [number, diger]);
+        }
+    }
+    /** One backed-off receipt attempt: submit when forced, elected or past the grace, else fetch. */
+    *pursueReceipts(event, serder, forceSubmit = false) {
+        const run = this.retain(event, {});
+        const now = this.clock.now();
+        run.since ??= now;
+        if (now < run.nextAt)
+            return;
+        const submit = forceSubmit || groupWitnesser(this.hby, event.pre, event) || now - run.since >= run.fallbackAfterMs;
+        try {
+            if (submit)
+                yield* this.receipting.receipt(event.pre, { sn: event.sn, auths: run.auths });
+            else
+                yield* this.receipting.get(event.pre, { sn: event.sn, said: event.said });
+            run.failure = null;
+            run.delay = this.receiptRetry.baseMs;
+        }
+        catch (error) {
+            // A witness refusing or being unreachable is a remote outcome: report it in status and retry later.
+            run.failure = error instanceof Error ? error.message : String(error);
+            run.delay = Math.min(run.delay * 2, this.receiptRetry.maxMs);
+        }
+        run.nextAt = now + run.delay;
+        if (!this.hby.db.fullyWitnessed(serder))
+            this.changes?.push({ kind: "group", id: `${event.pre}:${event.sn}` });
+    }
+    /** Remove a stale tuple when another SAID holds its sn; true when removed. */
+    dropIfSuperseded(table, event, number, diger) {
+        const accepted = this.hby.db.kels.getLast(event.pre, event.sn);
+        if (!accepted || accepted === event.said)
+            return false;
+        table.rem([event.pre], [number, diger]);
+        this.runs.delete(this.runKey(event));
+        this.changes?.push({ kind: "group", id: `${event.pre}:${event.sn}` });
+        return true;
+    }
+    /** Digest of the completed event at `(pre, sn)`, under either number width KERIpy writes. */
+    completed(pre, sn) {
+        const cgms = this.hby.db.cgms;
+        const auto = NumberPrimitive.fromNum(BigInt(sn));
+        const huge = new NumberPrimitive({ code: NumDex.Huge, raw: hugeRaw(sn) });
+        return (cgms.get([pre, auto.qb64]) ?? cgms.get([pre, huge.qb64]))?.qb64 ?? null;
+    }
+    /** Stage whose escrow holds exactly this event, if any. */
+    stageOf({ pre, sn, said }) {
+        for (const [stage, table] of STAGES) {
+            for (const [number, diger] of this.hby.db[table].get([pre])) {
+                if (Number(number.num) === sn && diger.qb64 === said)
+                    return stage;
+            }
+        }
+        return null;
+    }
+    refOf(pre, number, diger) {
+        return { pre, sn: Number(number.num), said: diger.qb64 };
+    }
+    runKey({ pre, sn, said }) {
+        return `${pre}:${sn}:${said}`;
+    }
+    /** Get or create the in-memory run for an event, applying supplied inputs. */
+    retain(event, { auths, fallbackAfterMs, proxy }) {
+        if (fallbackAfterMs !== undefined && !(fallbackAfterMs >= 0 && Number.isFinite(fallbackAfterMs))) {
+            throw new ValidationError("fallbackAfterMs must be a finite nonnegative duration.");
+        }
+        const key = this.runKey(event);
+        const run = this.runs.get(key)
+            ?? {
+                auths: {},
+                fallbackAfterMs: DEFAULT_FALLBACK_AFTER_MS,
+                since: null,
+                nextAt: 0,
+                delay: this.receiptRetry.baseMs,
+                failure: null,
+                proxy: null,
+                begun: false,
+            };
+        if (proxy) {
+            run.proxy = proxy;
+            run.begun = false; // the Anchorer pins its sender per begin, so re-pin
+        }
+        if (auths) {
+            run.auths = { ...auths };
+            run.nextAt = 0; // New credentials re-arm an attempt that was waiting out its backoff.
+        }
+        if (fallbackAfterMs !== undefined)
+            run.fallbackAfterMs = fallbackAfterMs;
+        this.runs.set(key, run);
+        return run;
+    }
+}
+/** Big-endian 16-byte raw for the `0A` (Huge) number code. */
+function hugeRaw(sn) {
+    const raw = new Uint8Array(16);
+    for (let at = 15, value = BigInt(sn); at >= 0; at--, value >>= 8n)
+        raw[at] = Number(value & 0xffn);
+    return raw;
+}
+/**
+ * Observe `event` until it is no longer pending or the deadline passes. Starts
+ * no worker and makes no receipt call; progress comes from `processOnce`
+ * running elsewhere.
+ */
+export function* waitForGroupEvent(counselor, event, { timeoutMs, clock }) {
+    const done = yield* observeUntil(() => counselor.status(event).state !== "pending", { timeoutMs, clock });
+    const status = counselor.status(event);
+    return done ? { outcome: "settled", status } : { outcome: "timed-out", status, timeoutMs };
+}

package/esm/keri/npm/src/app/multisig/group-members.js

@@ -78,6 +78,24 @@ export function groupElectedMember(hby, group, coordinator) {
         return null;
     return groupSigningMembers(hby, group).find(member => latestGroupContribution(hby.db, member, selection.establishment.verfers)?.index === selection.index) ?? null;
 }
+/**
+ * True when the local member is the witnesser for the exact accepted group event
+ * `coordinator`, as KERIpy `_groupWitnesser`: the member's latest contribution to
+ * the governing establishment's keys holds the lowest verified signing index.
+ *
+ * Unlike `groupElectedMember` this does not require that member to be a current
+ * signing member, so a historical event keeps its witnesser after a later
+ * rotation. Like it, the answer depends on locally stored signatures and suits
+ * idempotent duties only.
+ */
+export function groupWitnesser(hby, group, coordinator) {
+    const selection = groupWitnesserSelection(hby.db, group, coordinator);
+    if (!selection)
+        return false;
+    const member = localGroupMember(hby, group).pre;
+    const contribution = member ? latestGroupContribution(hby.db, member, selection.establishment.verfers) : null;
+    return contribution?.index === selection.index;
+}
 /** Return current group signing member AIDs in signing-index order. */
 export function groupSigningMembers(hby, groupPre) {
     const stored = hby.ks.getSmids(groupPre).map((tuple) => tuple[0].qb64);