keri-ts 2.0.1 → 2.2.0

package/esm/keri/npm/src/app/identity/delegation-approval.js

@@ -0,0 +1,333 @@
+/**
+ * Delegator-side approval of pending delegated events, owned by the library so
+ * that every host (CLI, wallet, service) runs one implementation.
+ *
+ * A delegate's `dip` or `drt` reaches the delegator's `delegables.` escrow. The
+ * delegator approves it by anchoring the event seal in its own KEL, then lets
+ * the delegate's event reach local state. Operations follow the workflow
+ * contract (`app/runtime/workflow-contract.ts`):
+ * - `listPendingDelegations` and `delegationApprovalStatus` are pure reads of
+ *   durable state.
+ * - `approveDelegation` is the only operation that signs. It returns after the
+ *   anchor is committed locally and the follow-up requests are sent.
+ * - `waitForPendingDelegation`, `waitForDelegationAnchor` and `waitForDelegationApproval`
+ *   only observe, each on the one thing asked for; the host's runtime workers make the
+ *   request and the delegate's event arrive.
+ * - `dismissDelegation` removes the local controller notice only.
+ *
+ * Idempotence evidence: the anchor is the seal `{i, s, d}` of the delegated event
+ * inside the delegator's own KEL. That KEL entry is durable the moment signing
+ * commits, so a repeated approval after a crash finds it and never anchors twice.
+ * Witness receipts are not part of the test on purpose: the sealing-event lookup
+ * of `Baser` requires them, which would re-anchor in the window between signing
+ * and receipting.
+ *
+ * - A group delegator's anchor is a group interaction: `proposeGroupDelegationApproval`
+ *   proposes it, the other members approve it with `approveGroupProposal`, and the
+ *   Counselor receipts it. `requestDelegatedEvent` then asks for the delegate's event.
+ *
+ * Boundaries:
+ * - Dependencies are declared collaborators, not an AgentRuntime (ADR-0013).
+ * - `approveDelegation` serves single-signature delegators and rejects a group.
+ * - Witness authorization codes arrive resolved. Prompting is a host concern.
+ */
+import { Diger } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
+import { dgKey } from "../../db/core/keys.js";
+import { proposeGroupInteraction } from "../multisig/proposing.js";
+import { observeUntil } from "../runtime/workflow-contract.js";
+import { DELEGATE_REQUEST_ROUTE } from "./delegating.js";
+import { isLocalGroupHab } from "./endpoint-roleing.js";
+import { receiptEvent } from "./event-completion.js";
+/** How long the CLI-compatible wait for the delegate's event lasts. */
+export const DELEGATION_APPROVAL_TIMEOUT_MS = 30_000;
+/** Delegator prefix for escrowed `dip` or `drt` material, if it is derivable. */
+function delegationSourcePrefix(db, serder, pre) {
+    if (serder.delpre)
+        return serder.delpre;
+    if (serder.ilk !== "drt")
+        return undefined;
+    const delegatedPre = serder.pre ?? pre;
+    return db.getKever(delegatedPre)?.delpre ?? db.getState(delegatedPre)?.di;
+}
+/** Project a delegated event into the seal the approving event embeds. */
+export function delegationSeal(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 requestFromEscrow(db, serder, pre) {
+    const delegator = delegationSourcePrefix(db, serder, pre);
+    if (!delegator)
+        return null;
+    const seal = delegationSeal(serder);
+    return {
+        delegate: seal.i,
+        sn: serder.sn ?? 0,
+        said: seal.d,
+        ilk: serder.ilk === "drt" ? "drt" : "dip",
+        delegator,
+    };
+}
+/** Find the delegator's KEL event that seals the request, whether or not it is receipted. */
+function findAnchor(db, request) {
+    for (const [, said] of db.getKelItemIter(request.delegator)) {
+        const serder = db.getEvtSerder(request.delegator, said);
+        for (const seal of serder?.seals ?? []) {
+            const { i, s, d } = (seal ?? {});
+            if (i === request.delegate && d === request.said && typeof s === "string" && parseInt(s, 16) === request.sn) {
+                return serder;
+            }
+        }
+    }
+    return null;
+}
+function anchorOf(serder) {
+    return { sn: serder.sn ?? 0, said: serder.said };
+}
+function inEscrow(db, request) {
+    return db.delegables.get([request.delegate]).includes(request.said);
+}
+/** True once the delegated event has left escrow and reached local state. */
+export function delegateCommitted(db, delegate, sn) {
+    const kever = db.getKever(delegate);
+    return kever !== undefined && kever !== null && kever.sn >= sn;
+}
+/** Witnesses of the delegate after the delegated event: `backs` of a `dip`, current witnesses otherwise. */
+export function delegateWitnesses(db, serder) {
+    if ((serder.sn ?? 0) === 0)
+        return [...serder.backs];
+    if (!serder.pre)
+        return [];
+    return [...(db.getKever(serder.pre)?.wits ?? [])];
+}
+/** Build the logs query that pulls the delegated event's replay from one delegate witness. */
+export function delegateWitnessLogsQuery(signer, serder, witness) {
+    if (!serder.pre || !serder.snh) {
+        throw new ValidationError("Delegated event is missing pre or sn for query.");
+    }
+    return {
+        pre: serder.pre,
+        signer,
+        src: witness,
+        route: "logs",
+        q: { fn: "0", s: serder.snh },
+        wits: [witness],
+    };
+}
+/** Record the approving seal for the delegated event and let the delegator's escrow promote it. */
+export 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();
+}
+/**
+ * List delegated events awaiting approval, oldest sequence first. Reads every
+ * `delegables.` row, with no cap, and skips rows whose delegated event already
+ * reached local state. Pure.
+ */
+export function listPendingDelegations(deps, { delegator } = {}) {
+    const { db } = deps;
+    const pending = [];
+    for (const [keys, said] of db.delegables.getTopItemIter()) {
+        const pre = keys[0];
+        const serder = pre ? db.getEvtSerder(pre, said) : null;
+        const request = serder && pre ? requestFromEscrow(db, serder, pre) : null;
+        if (!request || (delegator !== undefined && request.delegator !== delegator))
+            continue;
+        if (delegateCommitted(db, request.delegate, request.sn))
+            continue;
+        pending.push({ ...request, anchored: findAnchor(db, request) !== null });
+    }
+    return pending.sort((left, right) => left.sn - right.sn);
+}
+/** Read the durable status of one request; mutates nothing. */
+export function delegationApprovalStatus(deps, request) {
+    const { db } = deps;
+    const committed = delegateCommitted(db, request.delegate, request.sn);
+    if (!committed && !inEscrow(db, request))
+        return { state: "unknown", reason: "no-local-event" };
+    const anchor = findAnchor(db, request);
+    if (!anchor)
+        return { state: "awaiting-approval" };
+    if (committed)
+        return { state: "approved", anchor: anchorOf(anchor) };
+    return { state: "anchored", anchor: anchorOf(anchor), receipted: db.fullyWitnessed(anchor) };
+}
+/**
+ * Local step after anchoring: record the approving seal and process the
+ * `delegables.` escrow. Idempotent, sends nothing and signs nothing. It does
+ * nothing until the anchor exists and, for a delegate with witnesses, until the
+ * delegate's event has arrived through the witness replay, because pinning
+ * earlier would make local state look approved while incomplete.
+ */
+export function settleDelegationApproval(deps, request) {
+    const { hby } = deps;
+    const hab = hby.habs.get(request.delegator);
+    const delegated = hby.db.getEvtSerder(request.delegate, request.said);
+    const anchor = findAnchor(hby.db, request);
+    if (!hab || !delegated || !anchor)
+        return;
+    const witnessed = delegateWitnesses(hby.db, delegated).length > 0;
+    if (witnessed && !delegateCommitted(hby.db, request.delegate, request.sn))
+        return;
+    pinApprovalSeal(hby, hab, delegated, anchor);
+}
+/**
+ * Approve one delegated event: anchor its seal in the delegator's KEL unless
+ * the KEL already holds it, obtain witness receipts for the anchoring event and
+ * ask the delegate's witness for the delegated event. Returns without waiting
+ * for the delegate; use {@link waitForDelegationApproval}.
+ *
+ * Repeating the call after a failure resumes at the first step not yet done.
+ *
+ * @throws ValidationError for a request not held locally, a delegator that is not a local single-signature identifier, or an anchor that cannot be read back.
+ */
+export function* approveDelegation(deps, request, { event, auths }) {
+    const { hby } = deps;
+    const delegated = hby.db.getEvtSerder(request.delegate, request.said);
+    const status = delegationApprovalStatus(hby, request);
+    if (status.state === "unknown" || !delegated) {
+        throw new ValidationError(`No delegated ${request.ilk} ${request.said} is held for ${request.delegate}.`);
+    }
+    const hab = hby.habs.get(request.delegator);
+    if (!hab || isLocalGroupHab(hby, hab)) {
+        throw new ValidationError(`${request.delegator} is not a local single-signature delegator.`);
+    }
+    if (!hab.kever)
+        throw new ValidationError(`Missing accepted key state for ${hab.pre}.`);
+    let anchor = findAnchor(hby.db, request);
+    if (!anchor) {
+        const data = [delegationSeal(delegated)];
+        if (event === "ixn")
+            hab.interact({ data });
+        else
+            hab.rotate({ data });
+        anchor = findAnchor(hby.db, request);
+        if (!anchor)
+            throw new ValidationError("Approving event material is incomplete.");
+    }
+    yield* receiptEvent(deps, hab.pre, { sn: anchorOf(anchor).sn, auths });
+    requestDelegatedEvent(deps, request, hab.pre);
+    return delegationApprovalStatus(hby, request);
+}
+/**
+ * After the anchor exists: record the approving seal and ask the delegate's witness
+ * for the delegated event unless it already arrived. `signer` is the local identifier
+ * that sends the query: the delegator, or a group delegator's local member. Idempotent.
+ */
+export function requestDelegatedEvent(deps, request, signer) {
+    const { hby } = deps;
+    const delegated = hby.db.getEvtSerder(request.delegate, request.said);
+    if (!delegated) {
+        throw new ValidationError(`No delegated ${request.ilk} ${request.said} is held for ${request.delegate}.`);
+    }
+    settleDelegationApproval(deps, request);
+    const [witness] = delegateWitnesses(hby.db, delegated).sort();
+    if (!delegateCommitted(hby.db, request.delegate, request.sn)) {
+        // A delegate with no witness is asked through the same logs route with the usual attester choice.
+        deps.querying.enqueue(witness
+            ? delegateWitnessLogsQuery(signer, delegated, witness)
+            : { pre: request.delegate, signer, route: "logs", q: { fn: "0", s: delegated.snh } });
+    }
+    deps.changes?.push({ kind: "delegation", id: `${request.delegate}:${request.sn}` });
+}
+/**
+ * Propose a group delegator's anchoring interaction for one request: the group
+ * interaction that seals the delegated event, published to the other members.
+ * Returns without waiting; the other members approve it with `approveGroupProposal`
+ * and the Counselor receipts it, so read progress with `delegationApprovalStatus`
+ * and `counselor.status(result.event)`.
+ *
+ * Idempotent: null when the group's KEL already holds the anchor, so a repeat
+ * never anchors twice.
+ *
+ * @throws ValidationError for a request not held locally or a delegator that is not a local group.
+ */
+export function* proposeGroupDelegationApproval(deps, request, inputs) {
+    const { hby } = deps;
+    const delegated = hby.db.getEvtSerder(request.delegate, request.said);
+    if (delegationApprovalStatus(hby, request).state === "unknown" || !delegated) {
+        throw new ValidationError(`No delegated ${request.ilk} ${request.said} is held for ${request.delegate}.`);
+    }
+    const group = hby.habs.get(request.delegator);
+    if (!group || !isLocalGroupHab(hby, group)) {
+        throw new ValidationError(`${request.delegator} is not a local group delegator.`);
+    }
+    if (findAnchor(hby.db, request))
+        return null;
+    return yield* proposeGroupInteraction(deps, group, [delegationSeal(delegated)], inputs);
+}
+/**
+ * Observe until at least one delegated event awaits the delegator, or the budget
+ * expires. Waits on the delegator's own `delegables.` escrow only: unrelated
+ * group proposals, queries or OOBIs never hold it open. Starts no worker; the
+ * host's runtime brings the request in through its mailbox or witness polling.
+ *
+ * `timed-out` means no request reached local state in the budget, which is also
+ * what a request that was already approved and committed looks like.
+ */
+export function* waitForPendingDelegation(deps, filter = {}, { timeoutMs = DELEGATION_APPROVAL_TIMEOUT_MS } = {}) {
+    const done = yield* observeUntil(() => listPendingDelegations(deps, filter).length > 0, { timeoutMs });
+    const status = listPendingDelegations(deps, filter);
+    if (!done && status.length === 0)
+        return { outcome: "timed-out", status, timeoutMs };
+    for (const request of status)
+        deps.changes?.push({ kind: "delegation", id: `${request.delegate}:${request.sn}` });
+    return { outcome: "settled", status };
+}
+/**
+ * Observe a group delegator's request until its anchor is in the group's KEL and
+ * receipted by witnesses, or the delegate's event is already accepted. This is
+ * the point where {@link requestDelegatedEvent} can ask for the delegate's event.
+ */
+export function* waitForDelegationAnchor(deps, request, { timeoutMs = DELEGATION_APPROVAL_TIMEOUT_MS } = {}) {
+    const ready = (status) => status.state === "approved" || (status.state === "anchored" && status.receipted);
+    const done = yield* observeUntil(() => ready(delegationApprovalStatus(deps, request)), { timeoutMs });
+    const status = delegationApprovalStatus(deps, request);
+    if (!done && !ready(status))
+        return { outcome: "timed-out", status, timeoutMs };
+    return { outcome: "settled", status };
+}
+/**
+ * Observe the request until it is `approved` or the budget expires. Starts no
+ * worker; the host's runtime brings the delegate's event in.
+ */
+export function* waitForDelegationApproval(deps, request, { timeoutMs = DELEGATION_APPROVAL_TIMEOUT_MS } = {}) {
+    const read = () => {
+        deps.settle?.();
+        return delegationApprovalStatus(deps, request);
+    };
+    const done = yield* observeUntil(() => read().state === "approved", { timeoutMs });
+    const status = read();
+    if (!done || status.state !== "approved")
+        return { outcome: "timed-out", status, timeoutMs };
+    deps.changes?.push({ kind: "delegation", id: `${request.delegate}:${request.sn}` });
+    return { outcome: "settled", status };
+}
+/**
+ * Remove the controller notices (`/delegate/request`) that announced this
+ * request. Local only: the delegated event stays in escrow and the delegate is
+ * told nothing, so the request can still be approved or listed later.
+ *
+ * @returns Number of notices removed.
+ */
+export function dismissDelegation(deps, request) {
+    const stale = [];
+    for (let start = 0;; start += 25) {
+        const page = deps.notifier.list(start, 25);
+        for (const note of page) {
+            const attrs = note.pad.a;
+            const evt = attrs["ked"];
+            if (attrs["r"] === DELEGATE_REQUEST_ROUTE && attrs["delpre"] === request.delegator && evt?.d === request.said) {
+                stale.push(note.pad.i);
+            }
+        }
+        if (page.length < 25)
+            break;
+    }
+    return stale.filter((rid) => deps.notifier.remove(rid)).length;
+}

package/esm/keri/npm/src/app/identity/event-completion.js

@@ -0,0 +1,154 @@
+/**
+ * Single-signature event completion: the steps that follow authoring a local
+ * event, owned by the library so that every host (CLI, wallet, service) runs
+ * one implementation.
+ *
+ * Completion is two independent steps. `receiptEvent` obtains witness receipts
+ * for the accepted event. For delegated events, `beginDelegation` places the
+ * event in the durable delegating workflow and `waitForDelegation` drives the
+ * host's runtime has learned the delegator's anchor. Begin is separate from
+ * wait so that a host without a blocking caller can begin, return to its user
+ * interface and read `delegationStatus` later. `completeEvent` is the
+ * convenience that runs both steps in order. A completed rotation (`rot` or `drt`) is then announced with a
+ * {@link RotatedCue} to the host's `KelPublisher`, which tells the identifier's mailboxes (a mailbox
+ * authenticates the identifier's polls against the key state it holds). The announcement is a prompt:
+ * the publisher derives what is owed from state, so a host without one loses nothing durable. An interaction
+ * event changes no keys, so it announces nothing.
+ *
+ * Boundaries:
+ * - Dependencies are narrow collaborators, not an AgentRuntime (ADR-0013). The
+ *   host owns the runtime and its lifetime; `withDelegation` lends the
+ *   collaborator for one scope and, for a one-shot host, runs workers in it.
+ * - Waits only observe. They never start runtime workers, and an expired wait is
+ *   a returned `timed-out` value, not an exception.
+ * - Witness authorization codes arrive resolved. Prompting is a host concern.
+ * - Delegation state is the Anchorer's durable escrow membership; this module
+ *   adds none.
+ */
+import { Ilks } from "cesr-ts";
+import { dgKey } from "../../db/core/keys.js";
+import { observeUntil } from "../runtime/workflow-contract.js";
+import { Receiptor, WitnessReceiptor } from "../witness/receipting.js";
+/** How long the CLI-compatible wait for a delegator's anchor lasts. */
+export const DELEGATION_WAIT_TIMEOUT_MS = 120_000;
+/**
+ * Obtain witness receipts for an accepted local event. No-op when the
+ * identifier has no accepted key state yet (a delegated inception awaiting
+ * approval) or its current key state has no witnesses.
+ *
+ * @throws Receipt failures from the witness receiptor propagate.
+ */
+export function* receiptEvent(deps, pre, { sn, auths, endpoint = false, force = false } = {}) {
+    const kever = deps.hby.habs.get(pre)?.kever;
+    if (!kever?.wits.length)
+        return;
+    if (endpoint) {
+        yield* new Receiptor(deps.hby, deps.protocol, deps.http, deps.clock).receipt(pre, { sn, auths });
+    }
+    else {
+        yield* new WitnessReceiptor(deps.hby, deps.protocol, deps.http, deps.clock, { force })
+            .submit(pre, { sn, auths });
+    }
+    deps.changes?.push({ kind: "event", id: `${pre}:${sn ?? kever.sn}` });
+}
+/** Hex sequence key the delegating workflow uses. */
+function snKey(sn) {
+    return sn.toString(16);
+}
+/**
+ * Put one delegated event into the durable delegating workflow. Returns at once;
+ * progress needs the host's runtime workers, and `delegationStatus` reports it.
+ *
+ * @param communicationHab Optional local proxy that signs delegation traffic.
+ */
+export function beginDelegation(delegation, pre, sn, communicationHab) {
+    delegation.anchorer.beginLatest(pre, sn, { communicationHab });
+    delegation.changes?.push({ kind: "delegation", id: `${pre}:${sn}` });
+}
+/** Read the durable workflow state for one delegated event; mutates nothing. */
+export function delegationStatus(delegation, pre, sn) {
+    return delegation.anchorer.workflowStatus(pre, snKey(sn));
+}
+/**
+ * Observe the delegated event until the delegator's anchor is learned or the
+ * deadline passes. Starts no worker.
+ */
+export function* waitForDelegation(delegation, hab, sn, { timeoutMs = DELEGATION_WAIT_TIMEOUT_MS } = {}) {
+    const done = yield* observeUntil(() => delegation.anchorer.complete(hab.pre, sn), { timeoutMs });
+    const status = delegationStatus(delegation, hab.pre, sn);
+    if (!done)
+        return { outcome: "timed-out", status, timeoutMs };
+    delegation.changes?.push({ kind: "delegation", id: `${hab.pre}:${sn}` });
+    return { outcome: "settled", status };
+}
+/** Announce a completed rotation so its mailboxes are told; any other event announces nothing. */
+function announceRotation(deps, pre, sn, status) {
+    if (status.state !== "complete" || !deps.rotated)
+        return;
+    const said = deps.hby.db.kels.getLast(pre, sn);
+    const ilk = said ? deps.hby.db.getEvtSerder(pre, said)?.ilk : null;
+    if (said && (ilk === Ilks.rot || ilk === Ilks.drt))
+        deps.rotated.push({ kin: "rotated", pre, sn, said });
+}
+/**
+ * Complete a freshly authored event: witness receipts, then, for delegated
+ * events, delegation begin and wait.
+ *
+ * @param sn Sequence number of the event just authored.
+ */
+export function* completeEvent(deps, hab, sn, { delegation, ...receipt } = {}) {
+    yield* receiptEvent(deps, hab.pre, { ...receipt, sn });
+    if (!delegation) {
+        const status = eventStatus(deps.hby, hab.pre, sn);
+        announceRotation(deps, hab.pre, sn, status);
+        return { outcome: "settled", status, delegationPhase: null };
+    }
+    const communicationHab = delegation.communicationHab?.();
+    return yield* deps.withDelegation(hab, function* (collaborator) {
+        beginDelegation(collaborator, hab.pre, sn, communicationHab);
+        const result = yield* waitForDelegation(collaborator, hab, sn, { timeoutMs: delegation.timeoutMs });
+        const status = eventStatus({ db: deps.hby.db, anchorer: collaborator.anchorer }, hab.pre, sn);
+        if (result.outcome === "timed-out") {
+            return {
+                outcome: "timed-out",
+                status,
+                timeoutMs: result.timeoutMs,
+                delegationPhase: result.status.phase,
+            };
+        }
+        announceRotation(deps, hab.pre, sn, status);
+        return { outcome: "settled", status, delegationPhase: result.status.phase };
+    });
+}
+/**
+ * Pure synchronous status of the event `pre` at `sn`, derived from durable state.
+ *
+ * Receipts are judged against the witness set of THAT event (not the current
+ * key state) via stored `wigs`. A delegating-workflow escrow phase takes
+ * precedence; a delegated event with no escrow and no anchor yet reads as
+ * waiting for the delegator's anchor. Group events are not covered.
+ */
+export function eventStatus(deps, pre, sn) {
+    const workflow = deps.anchorer?.workflowStatus(pre, snKey(sn));
+    if (workflow?.phase)
+        return { state: "active", phase: workflow.phase };
+    const said = deps.db.kels.getLast(pre, sn);
+    const serder = said ? deps.db.getEvtSerder(pre, said) : null;
+    if (!said || !serder)
+        return { state: "unknown", reason: "no-accepted-event" };
+    if (!deps.db.fullyWitnessed(serder)) {
+        return {
+            state: "active",
+            phase: "waitingWitnessReceipts",
+            blocked: {
+                missing: "witnessReceipts",
+                have: deps.db.wigs.get(dgKey(pre, said)).length,
+                of: deps.db.acceptedEventWitnesses(serder)?.length ?? 0,
+            },
+        };
+    }
+    if (deps.anchorer && deps.db.getKever(pre)?.delegated && !deps.anchorer.complete(pre, sn)) {
+        return { state: "active", phase: "waitingDelegatorAnchor" };
+    }
+    return { state: "complete" };
+}