keri-ts 0.10.0 → 0.10.2

package/esm/keri/npm/src/app/cli/db-dump.js

@@ -0,0 +1,306 @@
+import { displayStr } from "../../core/bytes.js";
+import { DatabaseOperationError, ValidationError } from "../../core/errors.js";
+import { RawRecord } from "../../core/records.js";
+import { createBaser } from "../../db/basing.js";
+import { createKeeper } from "../../db/keeping.js";
+import { createMailboxer } from "../../db/mailboxing.js";
+import { createNoter } from "../../db/noting.js";
+import { createOutboxer } from "../../db/outboxing.js";
+const DOMAIN_FACTORIES = {
+    baser: {
+        open: (options) => createBaser(options),
+    },
+    keeper: {
+        open: (options) => createKeeper(options),
+    },
+    mailboxer: {
+        open: (options) => createMailboxer(options),
+    },
+    noter: {
+        open: (options) => createNoter(options),
+    },
+    outboxer: {
+        open: (options) => createOutboxer(options),
+    },
+};
+const DEFAULT_TARGET = "baser.evts";
+const DEFAULT_LIMIT = 50;
+const MAX_STRING_LENGTH = 240;
+function parseTarget(rawTarget) {
+    const target = rawTarget?.trim() || DEFAULT_TARGET;
+    const [domainRaw, storeName, extra] = target.split(".");
+    if (extra !== undefined) {
+        throw new ValidationError(`Invalid target "${target}". Use <domain> or <domain>.<subdb>.`);
+    }
+    if (domainRaw !== "baser"
+        && domainRaw !== "keeper"
+        && domainRaw !== "mailboxer"
+        && domainRaw !== "noter"
+        && domainRaw !== "outboxer") {
+        throw new ValidationError(`Unknown dump domain "${domainRaw}". Expected one of: baser, keeper, mailboxer, noter, outboxer.`);
+    }
+    return {
+        domain: domainRaw,
+        storeName,
+    };
+}
+function isDumpableStore(value) {
+    return typeof value === "object"
+        && value !== null
+        && (typeof value.getFullItemIter === "function"
+            || typeof value.getTopItemIter === "function");
+}
+function domainEntries(domain) {
+    return Object.entries(domain);
+}
+function collectStores(domain) {
+    return domainEntries(domain)
+        .filter(([, value]) => isDumpableStore(value))
+        .map(([name, value]) => [name, value])
+        .sort(([left], [right]) => left.localeCompare(right));
+}
+function resolveStore(domain, domainName, storeName) {
+    const value = domain[storeName];
+    if (!isDumpableStore(value)) {
+        const available = collectStores(domain).map(([name]) => `${domainName}.${name}`).join(", ");
+        throw new ValidationError(`Unknown target "${domainName}.${storeName}". Available targets: ${available}`);
+    }
+    return value;
+}
+function countStoreEntries(store) {
+    if (typeof store.cnt === "function") {
+        return store.cnt();
+    }
+    if (typeof store.cntAll === "function") {
+        return store.cntAll();
+    }
+    let count = 0;
+    for (const _ of iterateStore(store)) {
+        count += 1;
+    }
+    return count;
+}
+function* iterateStore(store, prefix = "") {
+    const iterator = typeof store.getFullItemIter === "function"
+        ? store.getFullItemIter(prefix)
+        : store.getTopItemIter?.(prefix);
+    if (!iterator) {
+        return;
+    }
+    for (const item of iterator) {
+        if (!Array.isArray(item)) {
+            continue;
+        }
+        if (item.length === 2) {
+            const [keys, value] = item;
+            yield {
+                keys: Array.isArray(keys) ? keys.map(String) : [String(keys)],
+                value,
+            };
+            continue;
+        }
+        if (item.length === 3) {
+            const [keys, on, value] = item;
+            yield {
+                keys: Array.isArray(keys) ? keys.map(String) : [String(keys)],
+                on: typeof on === "number" ? on : Number(on),
+                value,
+            };
+        }
+    }
+}
+function truncateString(value) {
+    if (value.length <= MAX_STRING_LENGTH) {
+        return value;
+    }
+    return `${value.slice(0, MAX_STRING_LENGTH - 3)}...`;
+}
+function normalizeDumpValue(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return truncateString(value);
+    }
+    if (typeof value === "number"
+        || typeof value === "boolean"
+        || typeof value === "bigint") {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return {
+            utf8: displayStr(value, MAX_STRING_LENGTH),
+            hex: truncateString(Array.from(value)
+                .map((byte) => byte.toString(16).padStart(2, "0"))
+                .join("")),
+        };
+    }
+    if (value instanceof RawRecord) {
+        return normalizeDumpValue(value.asDict());
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeDumpValue(item));
+    }
+    if (typeof value === "object") {
+        if ("qb64" in value && typeof value.qb64 === "string") {
+            return value.qb64;
+        }
+        if ("pad" in value && typeof value.pad === "object") {
+            return normalizeDumpValue(value.pad);
+        }
+        if ("sad" in value && typeof value.sad === "object") {
+            return normalizeDumpValue(value.sad);
+        }
+        if ("ked" in value && typeof value.ked === "object") {
+            return normalizeDumpValue(value.ked);
+        }
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .map(([key, entryValue]) => [key, normalizeDumpValue(entryValue)]));
+    }
+    return String(value);
+}
+function summarizeStoreCount(store) {
+    try {
+        return `${countStoreEntries(store)}`;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `error: ${truncateString(message)}`;
+    }
+}
+function printStoreSummary(domainName, domain) {
+    const stores = collectStores(domain);
+    console.log(`Domain summary for ${domainName}`);
+    console.log(`Resolved path: ${domain.path ?? "(closed)"}`);
+    console.log("");
+    console.log(`${"Target".padEnd(24)} ${"Type".padEnd(20)} Count`);
+    console.log("-".repeat(64));
+    for (const [name, store] of stores) {
+        console.log(`${`${domainName}.${name}`.padEnd(24)} ${store.constructor.name.padEnd(20)} ${summarizeStoreCount(store)}`);
+    }
+}
+function printStoreEntries(domainName, storeName, store, prefix, limit) {
+    const rows = [];
+    let total = 0;
+    for (const row of iterateStore(store, prefix)) {
+        total += 1;
+        if (rows.length < limit) {
+            rows.push(row);
+        }
+    }
+    console.log(`Target: ${domainName}.${storeName}`);
+    console.log(`Prefix: ${prefix || "(all)"}`);
+    console.log(`Entries shown: ${rows.length}/${total}`);
+    console.log("");
+    if (rows.length === 0) {
+        console.log("No matching entries.");
+        return;
+    }
+    rows.forEach((row, index) => {
+        console.log(JSON.stringify({
+            index: index + 1,
+            keys: row.keys,
+            ...(row.on !== undefined ? { on: row.on } : {}),
+            value: normalizeDumpValue(row.value),
+        }, null, 2));
+    });
+}
+function buildOptions(args) {
+    return {
+        name: args.name,
+        base: args.base,
+        headDirPath: args.headDirPath,
+        temp: args.temp,
+        compat: args.compat,
+        mapSize: args.mapSize,
+        reopen: true,
+        readonly: true,
+        dupsort: false,
+    };
+}
+function resolveMapSize(rawMapSize) {
+    if (rawMapSize === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(rawMapSize) || rawMapSize <= 0) {
+        throw new ValidationError("`--map-size` must be a positive integer byte count");
+    }
+    return rawMapSize;
+}
+function resolveLimit(rawLimit) {
+    if (rawLimit === undefined) {
+        return DEFAULT_LIMIT;
+    }
+    if (!Number.isInteger(rawLimit) || rawLimit <= 0) {
+        throw new ValidationError("`--limit` must be a positive integer");
+    }
+    return rawLimit;
+}
+/**
+ * Dump one LMDB domain summary or one specific subdb.
+ *
+ * Target examples:
+ * - `baser`
+ * - `baser.ends`
+ * - `mailboxer`
+ * - `mailboxer.tpcs`
+ * - `outboxer.tgts`
+ */
+export function* dumpDatabase(args) {
+    const name = args.name;
+    const base = args.base;
+    const headDirPath = args.headDirPath;
+    const temp = args.temp;
+    const compat = args.compat;
+    const mapSize = resolveMapSize(args.mapSize);
+    const target = args.target;
+    const prefix = args.prefix;
+    const limit = resolveLimit(args.limit);
+    if (!name) {
+        throw new ValidationError("`--name` is required");
+    }
+    const parsedTarget = parseTarget(target);
+    if (!parsedTarget.storeName && prefix) {
+        throw new ValidationError("`--prefix` requires a specific target like baser.locs or mailboxer.tpcs");
+    }
+    const domain = yield* DOMAIN_FACTORIES[parsedTarget.domain].open(buildOptions({
+        name,
+        base,
+        headDirPath,
+        temp,
+        compat,
+        mapSize,
+    }));
+    try {
+        console.log(`Dumping ${parsedTarget.storeName
+            ? `${parsedTarget.domain}.${parsedTarget.storeName}`
+            : parsedTarget.domain} from ${domain.path ?? "(unknown path)"}`);
+        console.log(`Mode: readonly compat=${compat ? "true" : "false"} temp=${temp ? "true" : "false"}${mapSize !== undefined ? ` mapSize=${mapSize}` : ""}`);
+        console.log("");
+        if (!parsedTarget.storeName) {
+            printStoreSummary(parsedTarget.domain, domain);
+            return;
+        }
+        const store = resolveStore(domain, parsedTarget.domain, parsedTarget.storeName);
+        printStoreEntries(parsedTarget.domain, parsedTarget.storeName, store, prefix ?? "", limit);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DatabaseOperationError(`Error dumping database: ${message}`, {
+            name,
+            base,
+            headDirPath,
+            temp,
+            compat,
+            target: target ?? DEFAULT_TARGET,
+            prefix: prefix ?? "",
+        });
+    }
+    finally {
+        yield* domain.close();
+    }
+}
+// Legacy export name kept so existing imports and tests do not break while the
+// command evolves past the original `evts`-only implementation.
+export const dumpEvts = dumpDatabase;

package/esm/keri/npm/src/app/cli/delegate.js

@@ -0,0 +1,305 @@
+/**
+ * Delegator-side CLI approval for pending delegated events.
+ *
+ * KERIpy correspondence:
+ * - this is the bounded command analogue of KLI's delegation approval flow
+ * - pending work is discovered from durable `delegables.` escrow, not from
+ *   controller notifications
+ *
+ * Maintainer rule:
+ * - `/delegate/request` notifications are UI hints only
+ * - approval ordering and event selection come from the delegated-event escrows
+ *   and the delegator's own KEL state
+ */
+import { Diger } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
+import { dgKey } from "../../db/core/keys.js";
+import { processRuntimeTurn, processRuntimeUntil, } from "../agent-runtime.js";
+import { groupSigningMembers, isLocalGroupHab, localGroupMember, } from "../endpoint-roleing.js";
+import { MULTISIG_IXN_ROUTE } from "../grouping.js";
+import { queryTransportSink } from "../query-transport.js";
+import { WitnessReceiptor } from "../witnessing.js";
+import { withHabAndAgentRuntime } from "./common/context.js";
+import { resolveWitnessAuths } from "./common/witness-auth.js";
+/** Return pending delegated events for one local delegator, oldest first. */
+function pendingDelegations(hby, delegatorPre) {
+    const pending = [];
+    for (const [keys, said] of hby.db.delegables.getTopItemIter()) {
+        const pre = keys[0];
+        if (!pre) {
+            continue;
+        }
+        const serder = hby.db.getEvtSerder(pre, said);
+        if (!serder) {
+            continue;
+        }
+        const sourcePrefix = delegationSourcePrefix(hby, serder, pre);
+        if (sourcePrefix !== delegatorPre) {
+            continue;
+        }
+        pending.push(serder);
+    }
+    return pending.sort((left, right) => (left.sn ?? 0) - (right.sn ?? 0));
+}
+/** Determine the delegator prefix for `dip` or `drt` escrow material. */
+function delegationSourcePrefix(hby, serder, pre) {
+    if (serder.delpre) {
+        return serder.delpre;
+    }
+    if (serder.ilk !== "drt") {
+        return undefined;
+    }
+    const delegatedPre = serder.pre ?? pre;
+    return hby.db.getKever(delegatedPre)?.delpre
+        ?? hby.db.getState(delegatedPre)?.di;
+}
+/** Project a delegated event into the seal embedded by the approving event. */
+function anchorData(serder) {
+    if (!serder.pre || !serder.snh || !serder.said) {
+        throw new ValidationError("Delegated event is missing pre, sn, or said.");
+    }
+    return { i: serder.pre, s: serder.snh, d: serder.said };
+}
+function approvingEvent(hby, serder, delegator) {
+    return hby.db.fetchLastSealingEventByEventSeal(delegator.pre, anchorData(serder));
+}
+/** Resolve delegate witnesses for either delegated inception or rotation. */
+function delegateWitnesses(hby, serder) {
+    if ((serder.sn ?? 0) === 0) {
+        return [...serder.backs];
+    }
+    if (!serder.pre) {
+        return [];
+    }
+    return [...(hby.db.getKever(serder.pre)?.wits ?? [])];
+}
+/** Return true once the delegated event has left escrow and reached local state. */
+function delegateCommitted(hby, serder) {
+    if (!serder.pre) {
+        return false;
+    }
+    const kever = hby.db.getKever(serder.pre);
+    return kever !== undefined && kever !== null && kever.sn >= (serder.sn ?? 0);
+}
+/** Build a witness log query used to pull delegate-side completion material. */
+function delegateWitnessLogsQuery(hab, serder, witness) {
+    if (!serder.pre || !serder.snh) {
+        throw new ValidationError("Delegated event is missing pre or sn for query.");
+    }
+    const query = { fn: "0", s: serder.snh };
+    return {
+        kind: "wire",
+        cue: {
+            kin: "query",
+            pre: serder.pre,
+            src: witness,
+            route: "logs",
+            query,
+            wits: [witness],
+        },
+        msgs: [hab.query(serder.pre, witness, query, "logs")],
+    };
+}
+function* publishGroupDelegationApproval(runtime, hby, groupHab, message) {
+    const member = localGroupMember(hby, groupHab.pre);
+    const smids = groupSigningMembers(hby, groupHab.pre);
+    const deliveries = [];
+    for (const recipient of smids) {
+        if (recipient === member.pre || hby.habs.has(recipient)) {
+            continue;
+        }
+        const result = yield* runtime.poster.sendExchange(member, {
+            recipient,
+            route: MULTISIG_IXN_ROUTE,
+            payload: { gid: groupHab.pre, smids },
+            embeds: { ixn: message },
+            topic: "multisig",
+        });
+        deliveries.push(...result.deliveries, ...result.queued);
+    }
+    return deliveries;
+}
+function eventAccepted(hby, serder) {
+    return !!serder.pre && serder.said !== undefined
+        && hby.db.kels.getLast(serder.pre, serder.sn ?? 0) === serder.said;
+}
+function pinApprovalSeal(hby, hab, delegated, approving) {
+    if (!approving.sner || !approving.said || !delegated.pre || !delegated.said) {
+        throw new ValidationError("Approving event material is incomplete.");
+    }
+    hby.db.aess.pin(dgKey(delegated.pre, delegated.said), [
+        approving.sner,
+        new Diger({ qb64: approving.said }),
+    ]);
+    hab.kvy.processEscrowDelegables();
+}
+/** Route query cues through query transport and other cues through Respondant. */
+function delegateConfirmSink(runtime, hby, hab) {
+    const querySink = queryTransportSink(runtime, hby, hab);
+    return {
+        *send(emission) {
+            if (emission.kind === "wire" && emission.cue.kin === "query") {
+                yield* querySink.send(emission);
+                return;
+            }
+            yield* runtime.respondant.sendWithHab(emission, hab);
+        },
+    };
+}
+/** Approve pending delegated events for the selected local delegator habitat.
+ *
+ * This is the explicit use-case service for the delegation approval workflow.
+ * The public CLI command is now a thin adapter: parse → open context → call → render → close.
+ */
+export function* performDelegationApproval(hby, hab, runtime, confirmArgs) {
+    const interactionApproval = confirmArgs.interact ?? false;
+    const sink = delegateConfirmSink(runtime, hby, hab);
+    yield* processRuntimeUntil(runtime, () => pendingDelegations(hby, hab.pre).length > 0, { hab, maxTurns: 64, pollMailbox: true, sink });
+    const pending = pendingDelegations(hby, hab.pre);
+    if (pending.length === 0) {
+        throw new ValidationError(`No delegated events are awaiting approval for ${hab.pre}.`);
+    }
+    if (pending.length > 1 && !confirmArgs.auto) {
+        throw new ValidationError(`Multiple delegated events are awaiting approval for ${hab.pre}. Re-run with --auto to approve them in order.`);
+    }
+    const auths = resolveWitnessAuths(hab.kever.wits, confirmArgs.code ?? [], {
+        codeTime: confirmArgs.codeTime,
+        promptMissing: confirmArgs.authenticate ?? false,
+    });
+    const selected = confirmArgs.auto ? pending : [pending[0]];
+    for (const serder of selected) {
+        const anchor = anchorData(serder);
+        if (isLocalGroupHab(hby, hab)) {
+            if (!interactionApproval) {
+                throw new ValidationError("Multisig delegated approval currently requires --interact.");
+            }
+            const approving = approvingEvent(hby, serder, hab);
+            if (!approving) {
+                const created = hby.interactGroupHab(confirmArgs.alias, undefined, { data: [anchor] });
+                const deliveries = yield* publishGroupDelegationApproval(runtime, hby, created.hab, created.message);
+                console.log(JSON.stringify({
+                    status: eventAccepted(hby, created.serder) ? "accepted" : "multisig-pending",
+                    route: MULTISIG_IXN_ROUTE,
+                    group: created.hab.pre,
+                    delegated: serder.pre,
+                    said: serder.said,
+                    anchor: created.serder.said,
+                    deliveries,
+                }));
+                continue;
+            }
+            const witnesses = delegateWitnesses(hby, serder).sort();
+            const selectedWitness = witnesses[0];
+            const member = localGroupMember(hby, hab.pre);
+            const memberSink = delegateConfirmSink(runtime, hby, member);
+            pinApprovalSeal(hby, hab, serder, approving);
+            yield* processRuntimeTurn(runtime, {
+                hab: member,
+                pollMailbox: true,
+                sink: memberSink,
+            });
+            if (!delegateCommitted(hby, serder) && selectedWitness) {
+                yield* memberSink.send(delegateWitnessLogsQuery(member, serder, selectedWitness));
+                yield* processRuntimeUntil(runtime, () => delegateCommitted(hby, serder), { hab: member, maxTurns: 128, pollMailbox: true, sink: memberSink });
+            }
+            pinApprovalSeal(hby, hab, serder, approving);
+            yield* processRuntimeTurn(runtime, {
+                hab: member,
+                pollMailbox: true,
+                sink: memberSink,
+            });
+            if (serder.pre && serder.said) {
+                const stillPending = hby.db.delegables.get([serder.pre]).includes(serder.said);
+                if (stillPending) {
+                    throw new ValidationError(`Delegated event ${serder.said} remained in delegables escrow after approval.`);
+                }
+            }
+            console.log(`Approved delegated ${serder.ilk} ${serder.said ?? ""} for ${serder.pre ?? ""} using multisig ixn.`);
+            continue;
+        }
+        // KERIpy permits either interaction or rotation approval. Keep this
+        // explicit because the chosen approving event type affects later
+        // replay, but the embedded anchor seal is the same.
+        if (interactionApproval) {
+            hab.interact({ data: [anchor] });
+        }
+        else {
+            hab.rotate({ data: [anchor] });
+        }
+        if (hab.kever?.wits.length) {
+            const witDoer = new WitnessReceiptor(hby);
+            yield* witDoer.submit(hab.pre, {
+                sn: hab.kever.sn,
+                auths,
+            });
+        }
+        const approving = hby.db.getEvtSerder(hab.pre, hab.kever.said);
+        if (!approving) {
+            throw new ValidationError("Approving event material is incomplete.");
+        }
+        const witnesses = delegateWitnesses(hby, serder).sort();
+        const selectedWitness = witnesses[0];
+        if (selectedWitness) {
+            // Witnessed delegates must prove the delegated event is committed
+            // locally before we pin `aess.` and retry delegated unescrow. Doing
+            // it earlier can make local state look approved but incomplete.
+            yield* sink.send(delegateWitnessLogsQuery(hab, serder, selectedWitness));
+            yield* processRuntimeUntil(runtime, () => delegateCommitted(hby, serder), { hab, maxTurns: 128, pollMailbox: true, sink });
+        }
+        else {
+            const querier = runtime.querying.watchSeqNo(serder.pre, serder.sn ?? 0, { hab });
+            // No delegate witness exists to query. Process the local delegable
+            // after the delegator has anchored approval; the delegate still
+            // discovers approval through its own delegator-KEL query path.
+            pinApprovalSeal(hby, hab, serder, approving);
+            yield* processRuntimeUntil(runtime, () => querier.done, { hab, maxTurns: 128, pollMailbox: true, sink });
+        }
+        yield* processRuntimeTurn(runtime, { hab, pollMailbox: true, sink });
+        // Match KERIpy sequencing: only record the approving seal and retry
+        // delegated unescrow after the delegate event has been observed as
+        // locally committed through the witness-backed query/replay path.
+        if (selectedWitness) {
+            pinApprovalSeal(hby, hab, serder, approving);
+        }
+        if (serder.pre && serder.said) {
+            const stillPending = hby.db.delegables.get([serder.pre]).includes(serder.said);
+            if (stillPending) {
+                throw new ValidationError(`Delegated event ${serder.said} remained in delegables escrow after approval.`);
+            }
+        }
+        console.log(`Approved delegated ${serder.ilk} ${serder.said ?? ""} for ${serder.pre ?? ""} using ${interactionApproval ? "ixn" : "rot"}.`);
+    }
+}
+/** Approve pending delegated events for the selected local delegator habitat. */
+export function* delegateConfirmCommand(args) {
+    const confirmArgs = {
+        name: args.name,
+        base: args.base,
+        headDirPath: args.headDirPath,
+        passcode: args.passcode,
+        alias: args.alias,
+        compat: args.compat,
+        interact: args.interact,
+        auto: args.auto,
+        authenticate: args.authenticate,
+        code: args.code,
+        codeTime: args.codeTime,
+    };
+    if (!confirmArgs.name) {
+        throw new ValidationError("Name is required and cannot be empty");
+    }
+    if (!confirmArgs.alias) {
+        throw new ValidationError("Alias is required and cannot be empty");
+    }
+    yield* withHabAndAgentRuntime(confirmArgs, confirmArgs.alias, {
+        compat: confirmArgs.compat ?? false,
+        readonly: false,
+        skipConfig: true,
+        skipSignator: true,
+    }, function* ({ hby, hab, runtime }) {
+        if (!hab.kever) {
+            throw new ValidationError(`Missing accepted key state for ${hab.pre}.`);
+        }
+        yield* performDelegationApproval(hby, hab, runtime, confirmArgs);
+    });
+}