keri-ts 2.1.0 → 2.2.1

package/esm/keri/npm/src/app/ipex/issuance.js

@@ -0,0 +1,896 @@
+/**
+ * Runtime-owned operations for single-signature v2 DH issuance.
+ *
+ * One `IssuanceOperations` owner holds an in-memory table of live operations. The user begins an
+ * operation with `beginIssuance`, which signs the Grant, approves the DH exchange, starts the query
+ * and records that authorisation in memory. The host's runtime loop (or, in a one-shot CLI, a driver
+ * under `withRuntimeWorkers`) then calls `processOnce`, which performs exactly the steps
+ * `tufa ipex --issue` performed itself: send the proof support and Grant, deliver DH traffic, resend
+ * a freshly dated query each second until DH completes, and once DH completes stage and anchor the registry update (BUP),
+ * `finish` the Grant and send the final proof support. Nothing starts an operation or signs except
+ * inside an operation the user began while its in-memory authorisation lives.
+ *
+ * Workflow-contract shape (`app/runtime/workflow-contract.ts`): `beginIssuance` returns after local
+ * commit and never waits for the peer; `issuanceStatus` is a pure read; `waitForIssuance` only
+ * observes and returns a `WaitResult`; `abandonIssuance` is local.
+ *
+ * There is no operation store. Status is derived from the protocol stores plus the live table, so a
+ * reopened store reads what the stores prove, whatever the process was doing:
+ *
+ * | stores prove                                                              | status                                   |
+ * | ------------------------------------------------------------------------- | ---------------------------------------- |
+ * | holder: pending Grant, no root held                                       | `awaitingExchangeConsent`                |
+ * | pending Grant past its deadline                                           | `expired`                                |
+ * | holder: root held, not committed otherwise; issuer: update accepted       | `active`, `rootRetained` (adopted)       |
+ * | issuer: pending Grant, update not accepted                                | `interrupted`                            |
+ * | root held and the registry committed to another exchange                  | `interrupted`                            |
+ * | holder: Grant accepted, no accepted Admit                                 | `active`, `awaitingAdmitConsent`         |
+ * | holder: accepted Admit                                                    | `done`, `admitted`                       |
+ * | issuer: Grant accepted                                                    | `done`, `issued`                         |
+ *
+ * Lost on reload, by design: the phases that live only in memory (`exchangingKeys`, `awaitingAnchor`,
+ * `proving` read `rootRetained` or `interrupted` afterwards), the `abandoned` and `failed` end states
+ * with their reasons (an abandoned holder reads `awaitingExchangeConsent` again, an abandoned issuer
+ * `interrupted`, and an abandoned operation whose root and accepted update remain is adopted and
+ * completed on the next start; it signs nothing and Admit stays a separate consent), the consent
+ * timestamps, and whether the issuer's final proof support was delivered (an issuer whose Grant is
+ * accepted reads `done` even if the process ended before that message went out). A Grant the issuer
+ * prepared but never began reads `interrupted`, the same as one whose process ended; so does an issuer
+ * that ended between staging its registry update and anchoring it (an explicit recovery action for that
+ * case is a planned follow-up; until then it needs a new Grant, and a held root nothing committed to is
+ * replaced). A wallet that wants any of these keeps them itself from the `ChangeSink`.
+ *
+ * After a restart the first `processOnce` finds the pending Grants this runtime's identifiers are party
+ * to that hold a root and can finish without new key exchange ({@link resumableExchange}) and adopts
+ * them: the holder waits for or verifies the issuer's update, an issuer whose update is already
+ * accepted finishes. Neither signs: the issuer's update was anchored before the restart, and
+ * `Dhke.finish` only proves the held root against the accepted update before the Grant is accepted. A
+ * new Grant on a registry that holds an unused root (no update staged or accepted) replaces that root
+ * when its exchange retains its own; otherwise the refusal stands. A KERIpy peer keeps the old rule and
+ * refuses a second exchange on a registry it holds a root for. The Grant's exchange deadline bounds
+ * everything, even a late completion; passing it reads `expired`.
+ *
+ * The runtime never writes wallet inventory. Completion is pushed to the `ChangeSink` as
+ * `{kind: "issuance", id: <grant>}` and the embedder records it.
+ *
+ * A local group issues and receives through the same table, status and wait: its consent calls and per-operation
+ * steps are in `group-issuance.ts` and run inside the same `processOnce`. A group exchange is not resumed after a
+ * restart (its frozen coordinator and custodian are not stored): a group pending Grant with no root reads
+ * `awaitingExchangeConsent`, and a member consents again with the same call.
+ *
+ * Collaborators are narrow concrete owners (ADR-0013); no `AgentRuntime`.
+ */
+import { collectPayload, concatBytes, Counter, framePayload, parseBytes, SerderACDC, Vrsn_2_0, } from "cesr-ts";
+import { call, race } from "effection";
+import { RegistryAuthor } from "../../acdc/authoring.js";
+import { RegistryCustody } from "../../acdc/custody.js";
+import { grantTransactionId, registryUncommitted, resumableExchange } from "../../acdc/dhking.js";
+import { ValidationError } from "../../core/errors.js";
+import { CREDENTIAL_MAILBOX_TOPIC } from "../../core/mailbox/mailbox-topics.js";
+import { timestampMicros } from "../../time/mod.js";
+import { isLocalGroupHab } from "../multisig/group-members.js";
+import { DeliveryOutbox, } from "../runtime/delivery-outbox.js";
+import { observeUntil, waitOnClock } from "../runtime/workflow-contract.js";
+import { deriveGroupCustody, GroupIssuance, GroupParty, registerGroupRoutes, stepGroup, } from "./group-issuance.js";
+import { IpexAdmitter } from "./ipex-admitting.js";
+import { exchangeWire, IpexDiscloser, storedExchangeWire } from "./ipex-discloser.js";
+/**
+ * Milliseconds between resends of the issuer query. Each resend is a new query (new date, SAID and signatures):
+ * the peer's KRAM caches every query it accepts, so an identical resend is a replay it drops, which would
+ * strand a peer that took the first query and then lost it before consenting (a process that ended, or a
+ * retained query that outlived its window).
+ */
+export const ISSUANCE_QUERY_RESEND_MS = 1000;
+/**
+ * Milliseconds between scans of the pending exchange escrow for Grants a restarted process can finish. The scan
+ * repeats because what makes a Grant resumable can arrive after the restart (an issuer's update accepted once the
+ * other members approve it).
+ */
+export const ISSUANCE_SWEEP_MS = 5_000;
+/**
+ * Adapt a `Poster`; its delivery worker must be running (a one-shot CLI runs it under `withRuntimeWorkers`).
+ * A wire of several complete messages (proof support plus Grant) goes as one ordered stream, which mailbox
+ * forwarding needs; a single message goes as an ordinary send, which is what a direct peer's query route expects.
+ */
+export function posterDelivery(postman) {
+    return {
+        *deliver({ src, dest, msg, topic = CREDENTIAL_MAILBOX_TOPIC }) {
+            const event = { src, dest, topic };
+            const sent = parseBytes(msg).length > 1
+                ? postman.sendStream({ ...event, msgs: [msg] }, { notify: true })
+                : postman.send({ ...event, msg }, { notify: true });
+            const outcome = yield* postman.wait(sent);
+            if (outcome.kin === "failed")
+                throw outcome.error;
+            return outcome.deliveries;
+        },
+    };
+}
+/** How long delivery failures may last on an operation that has no Grant deadline yet before it ends `failed`. */
+export const ISSUANCE_RETRY_BOUND_MS = 600_000;
+const EXPIRED = "The selected Grant reached its original exchange deadline";
+const EXPIRED_LATE = "The selected Grant reached its original exchange deadline after the issuer's registry update arrived; a Grant is completed only while live, so ask the issuer for a new Grant";
+const RESTARTED = "No live issuance holds this Grant: the process that began it ended before the registry update was anchored (or it was never begun); nothing was signed since. Begin the Grant, or a new one: its key exchange replaces any unused root";
+const COMMITTED = "The process that ended a key exchange left a staged or accepted registry update that this Grant can no longer complete, and the registry cannot take another key exchange";
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The live operations table and its driver. One per host runtime; every identifier of that runtime may
+ * issue through it. Only `processOnce` performs work, and only for operations in
+ * {@link IssuanceOperations.live}.
+ */
+export class IssuanceOperations {
+    constructor(deps) {
+        Object.defineProperty(this, "deps", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: deps
+        });
+        /** Operations live in this process. Internal to this module's functions. */
+        Object.defineProperty(this, "live", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** Operations that ended in this process with their reasons; not durable, see the module doc. */
+        Object.defineProperty(this, "ended", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "discloser", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The DH child handlers this owner registered on the multiplexor, once a group operation began. */
+        Object.defineProperty(this, "groupRoutes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** When the next scan for resumable Grants is due (host clock, ms); 0 until the first pass. */
+        Object.defineProperty(this, "nextSweep", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /** Grants a scan found resumable and adoption refused; they are not tried again in this process. */
+        Object.defineProperty(this, "refused", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        /** Grants an earlier process left resumable: each is adopted once, or dropped. */
+        Object.defineProperty(this, "stale", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        this.discloser = new IpexDiscloser(deps.hby, deps.rgy.store, deps.exc, deps.receiptor);
+    }
+    /** Whether a pass has work: a live operation, or the one-time scan for resumable Grants has not run. */
+    active() {
+        return this.live.size > 0 || this.stale.length > 0 || this.deps.clock.now() >= this.nextSweep;
+    }
+    /**
+     * Advance every live operation by one pass. Each pass is bounded by the operation's Grant deadline.
+     * The first pass also adopts the pending Grants the stores prove resumable ({@link resumableGrants});
+     * that signs and sends nothing.
+     */
+    *processOnce() {
+        if (this.deps.clock.now() >= this.nextSweep) {
+            this.nextSweep = this.deps.clock.now() + ISSUANCE_SWEEP_MS;
+            const known = new Set(this.stale.map(({ grant }) => grant));
+            this.stale.push(...resumableGrants(this.deps).filter(({ grant }) => !this.live.has(grant) && !known.has(grant) && !this.refused.has(grant) && !this.ended.has(grant)));
+        }
+        for (const found of [...this.stale]) {
+            if (yield* this.settle(found))
+                this.stale.splice(this.stale.indexOf(found), 1);
+        }
+        for (const op of [...this.live.values()]) {
+            if (op.busy || !this.live.has(op.grant))
+                continue;
+            op.busy = true;
+            try {
+                const left = op.expires === null ? null : op.expires - BigInt(this.deps.clock.now()) * 1000n;
+                if (left !== null && left <= 0n)
+                    this.end(op, "expired", EXPIRED);
+                else if ((yield* race([this.advance(op), ...(left === null ? [] : [this.timer(Number(left) / 1000)])])) === "expired")
+                    this.end(op, "expired", EXPIRED);
+            }
+            catch (error) {
+                this.end(op, "failed", message(error));
+            }
+            finally {
+                op.busy = false;
+            }
+        }
+    }
+    /** End a live operation: release its DH approval, remember why until the process ends, tell the sink. */
+    end(op, state, reason) {
+        this.release(op);
+        this.ended.set(op.grant, { role: op.role, state, reason });
+        this.deps.changes?.push({ kind: "issuance", id: op.grant });
+    }
+    /** Drop the live entry and the DH approval; a missing approval means the owner already closed. */
+    release(op) {
+        this.live.delete(op.grant);
+        try {
+            op.dh.abandon(op.xid);
+        }
+        catch (error) {
+            if (!(error instanceof ValidationError))
+                throw error;
+        }
+    }
+    /**
+     * Adopt one Grant an earlier process left resumable, without signing: the holder waits for or verifies the
+     * update, an issuer whose update is already accepted finishes. A Grant the exchange can no longer resume is
+     * dropped and reads from the stores. False means the Keeper is locked and the Grant is retried.
+     */
+    *settle(found) {
+        if (this.live.has(found.grant))
+            return true;
+        try {
+            found.hab.mgr.requireRegistryRootAccess();
+        }
+        catch (error) {
+            if (error instanceof ValidationError)
+                return false;
+            throw error;
+        }
+        // Another operations table over this runtime reached the Grant first (a command's own, beside the host's).
+        if (this.deps.dhkes.dhke(found.hab).holds(found.grant)) {
+            this.refused.add(found.grant);
+            return true;
+        }
+        try {
+            yield* this.adopt(found);
+        }
+        catch (error) {
+            this.refused.add(found.grant);
+            // A refusal means the stores no longer prove it resumable and status reads from them; anything else is
+            // this Grant's failure alone and must not stop the other operations.
+            if (!(error instanceof ValidationError)) {
+                this.ended.set(found.grant, { role: found.role, state: "failed", reason: message(error) });
+                this.deps.changes?.push({ kind: "issuance", id: found.grant });
+            }
+        }
+        return true;
+    }
+    /** Rebuild the live entry of a resumable Grant from the stored Grant and the held roots. */
+    *adopt({ hab, grant, role }) {
+        const group = isLocalGroupHab(this.deps.hby, hab);
+        const { retained, credential, deadline, expires } = selectGrant(this, hab, grant, role, group);
+        if (group) {
+            this.adoptGroup(hab, grant, role, retained);
+            return;
+        }
+        const wires = role === "issuer" ? yield* grantWires(retained) : null;
+        const dh = this.deps.dhkes.dhke(hab), xid = dh.resume(grant);
+        this.ended.delete(grant);
+        this.live.set(grant, {
+            grant,
+            xid,
+            role,
+            deadline,
+            hab,
+            dh,
+            peer: wires ? retained.serder.sad.ri : retained.serder.pre,
+            registry: credential.regid,
+            expires,
+            issuer: wires ? { credential, ...wires, query: null, sent: true, nextQuery: 0 } : undefined,
+            phase: "rootRetained",
+            outbox: new DeliveryOutbox(this.deps.retry),
+            finished: false,
+            busy: false,
+        });
+        this.deps.changes?.push({ kind: "issuance", id: grant });
+    }
+    /**
+     * Adopt a group custodian's completed exchange after a restart, signing nothing: the coordinator and custodian
+     * the exchange was frozen with are derived from the stores ({@link deriveGroupCustody}), the holder's root is
+     * already held, and the group steps finish the Grant against the accepted update. The only signature is the
+     * endorsement of the public proof wrapper the original consent already covers.
+     */
+    adoptGroup(hab, grant, role, retained) {
+        const election = deriveGroupCustody(this.deps, hab, grant);
+        const party = GroupParty.resolve(this.deps, hab, election.coordinator.said);
+        const group = new GroupIssuance(party, role, retained.serder, retained.nests ?? [], { mode: "resumed" });
+        const dh = this.deps.dhkes.dhke(hab), xid = dh.resume(grant, party);
+        this.ended.delete(grant);
+        this.live.set(grant, this.liveGroup(group, dh, xid, "rootRetained"));
+        this.deps.changes?.push({ kind: "issuance", id: grant });
+    }
+    /** The live entry of a group operation; its lifetime is the Grant's once KRAM has accepted it, else unknown. */
+    liveGroup(group, dh, xid, phase) {
+        const deadline = this.deps.exc.exchangeDeadline(group.grant), expires = deadline ? timestampMicros(deadline) : null;
+        return {
+            grant: group.said,
+            xid,
+            role: group.role,
+            deadline,
+            hab: group.party.group,
+            dh,
+            peer: group.peer,
+            registry: group.registry,
+            expires,
+            group,
+            phase,
+            outbox: new DeliveryOutbox(),
+            finished: false,
+            busy: false,
+        };
+    }
+    *timer(milliseconds) {
+        yield* waitOnClock(this.deps.clock, milliseconds);
+        return "expired";
+    }
+    /**
+     * Queue signed bytes for delivery from the identifier that signed them. Steps decide what to send; {@link drain}
+     * sends it, so a member that is briefly offline delays the operation instead of ending it.
+     */
+    enqueue(op, message) {
+        op.outbox.enqueue(message);
+    }
+    /**
+     * Deliver the queued messages in order. A failure keeps the message and schedules a retry with a doubling delay;
+     * it ends the operation only where nothing else bounds it: the Grant deadline ends one that has it, and failures
+     * lasting {@link ISSUANCE_RETRY_BOUND_MS} end one that has none yet. True when the outbox is empty.
+     */
+    *drain(op) {
+        return yield* op.outbox.drain(this.deps.delivery, this.deps.clock, op.expires === null ? this.deps.retry?.boundMs ?? ISSUANCE_RETRY_BOUND_MS : undefined);
+    }
+    /** One pass: send what is queued, step only once the queue is empty, send what the step queued. */
+    *advance(op) {
+        if (!(yield* this.drain(op)))
+            return "stepped";
+        if (!op.finished)
+            yield* this.step(op);
+        if ((yield* this.drain(op)) && op.finished) {
+            this.release(op);
+            this.deps.changes?.push({ kind: "issuance", id: op.grant });
+        }
+        return "stepped";
+    }
+    /** Record a phase change of a live operation and tell the sink; the group steps call it too. */
+    setPhase(op, phase) {
+        if (op.phase === phase)
+            return;
+        op.phase = phase;
+        this.deps.changes?.push({ kind: "issuance", id: op.grant });
+    }
+    /**
+     * Record one group operation the user consented to ({@link approveGroupIssuance},
+     * {@link approveGroupIssuanceExchange}, {@link followGroupIssuanceProof}). A holder approves DH here, with its
+     * consent; an issuer approves once the group has authenticated the Grant.
+     */
+    beginGroup(group) {
+        const { deps } = this, { party } = group;
+        registerGroupRoutes(this);
+        const dh = deps.dhkes.dhke(party.group);
+        // A holder approves DH with its consent; an issuer approves once the group has authenticated the Grant.
+        const holder = group.role === "holder" && group.mode !== "proofOnly";
+        const xid = holder ? dh.approve(group.said, party) : group.xid;
+        group.approved = holder;
+        const phase = group.mode === "proofOnly"
+            ? "awaitingAnchor"
+            : group.role === "issuer"
+                ? "awaitingGrantSignatures"
+                : "exchangingKeys";
+        this.ended.delete(group.said);
+        this.live.set(group.said, this.liveGroup(group, dh, xid, phase));
+        deps.changes?.push({ kind: "issuance", id: group.said });
+        return { grant: group.said, xid };
+    }
+    /** Whether the live operation for `grant` still holds a message the transport has not taken. */
+    owes(grant) {
+        return (this.live.get(grant)?.outbox.length ?? 0) > 0;
+    }
+    /** One pass of the issuer loop, in the order of the CLI loop it replaces. */
+    *step(op) {
+        if (op.group) {
+            op.finished = yield* stepGroup(this, op);
+            return "stepped";
+        }
+        const issuer = op.issuer;
+        if (issuer && !issuer.sent) {
+            this.enqueue(op, {
+                src: op.hab.pre,
+                dest: op.peer,
+                msg: concatBytes(this.discloser.proofSupport(issuer.raw, op.hab), issuer.grantWire),
+            });
+            issuer.sent = true;
+        }
+        while (op.dh.outgoing.length) {
+            const queued = op.dh.outgoing.pull();
+            if (queued.kin === "sign")
+                throw new ValidationError("Individual issuance cannot process group contributions");
+            this.enqueue(op, { src: op.hab.pre, dest: queued.dest, msg: queued.msg });
+        }
+        if (!op.dh.complete(op.xid)) {
+            if (issuer?.query && this.deps.clock.now() >= issuer.nextQuery) {
+                this.enqueue(op, { src: op.hab.pre, dest: op.peer, msg: () => this.renewed(op, issuer) });
+                issuer.nextQuery = this.deps.clock.now() + (this.deps.queryResendMs ?? ISSUANCE_QUERY_RESEND_MS);
+            }
+        }
+        else if (issuer)
+            yield* this.finish(op, issuer);
+        else
+            yield* this.receive(op);
+        return "stepped";
+    }
+    /**
+     * The query to resend now, signed afresh (`Dhke.requery`: same keys and scope, new `dt`, SAID and signatures).
+     * An unchanged resend is a KRAM replay once the peer has accepted the original, so it can never reach a peer
+     * that lost it; a new query is timely whatever window the peer runs. Re-signing happens only here, inside the
+     * live authorisation that began the operation; with the Keeper locked the last query goes again unchanged. A
+     * group threshold query cannot be re-dated by one member; group issuance is not run here.
+     */
+    renewed(op, issuer) {
+        try {
+            op.hab.mgr.requireRegistryRootAccess();
+        }
+        catch (error) {
+            if (error instanceof ValidationError)
+                return issuer.query;
+            throw error;
+        }
+        issuer.query = op.dh.requery(op.xid);
+        return issuer.query;
+    }
+    /**
+     * Holder, DH complete: wait for the issuer's registry update, then verify it and finish the Grant. The
+     * issuance is then complete but for the holder's separate Admit consent.
+     */
+    *receive(op) {
+        if (this.deps.rgy.store.headEvent(op.registry)?.ilk === "rip")
+            return this.setPhase(op, "rootRetained");
+        this.setPhase(op, "proving");
+        yield* op.dh.finish(op.xid);
+        if (!this.deps.exc.complete(op.grant))
+            throw new ValidationError("Issued Grant remains unaccepted");
+        op.finished = true;
+    }
+    /** DH is complete: stage and anchor the BUP under the live authorisation, finish the Grant, send proof support. */
+    *finish(op, issuer) {
+        const { rgy, receiptor, derived } = this.deps;
+        // An accepted update means a restart came after the anchor: never stage a second one. `Dhke.finish` below
+        // proves the head opens this credential as issued against the held root, or the issuance fails.
+        if (rgy.store.headEvent(op.registry)?.ilk === "rip") {
+            this.setPhase(op, "awaitingAnchor");
+            const reg = rgy.regs.get(op.registry);
+            const custody = new RegistryCustody({ hby: this.deps.hby, hab: op.hab, registry: rgy.store, store: derived });
+            const author = new RegistryAuthor(rgy, receiptor, custody);
+            const { event } = author.stage(reg, issuer.credential, "issued", { auths: issuer.auths });
+            yield* author.anchor(reg, event, issuer.auths);
+        }
+        this.setPhase(op, "proving");
+        yield* op.dh.finish(op.xid);
+        if (!this.deps.exc.complete(op.grant))
+            throw new ValidationError("Issued Grant remains unaccepted");
+        this.enqueue(op, { src: op.hab.pre, dest: op.peer, msg: this.discloser.proofSupport(issuer.raw, op.hab) });
+        op.finished = true;
+    }
+}
+/** Whether the clock has reached a Grant deadline in microseconds since the epoch. */
+function reached(clock, expires) {
+    return expires !== null && BigInt(clock.now()) * 1000n >= expires;
+}
+/**
+ * Whether a restarted process can complete this Grant without a new key exchange: it is pending inside its
+ * deadline, `hab` is the party `role` names, and {@link resumableExchange} finds the roots. An issuer
+ * additionally needs its update already accepted; one that is not anchored cannot be resumed, since the
+ * anchor would be signed after the restart. A pure read of stores.
+ */
+function resumable(deps, hab, grant, role) {
+    // A group exchange resumes only on the member the stores show to be its custodian.
+    if (isLocalGroupHab(deps.hby, hab) && !deriveGroupCustody(deps, hab, grant))
+        return false;
+    const scope = resumableExchange({ hab, exc: deps.exc }, grant);
+    if (!scope || (scope.issuer === hab.pre) !== (role === "issuer"))
+        return false;
+    return role === "holder" || scope.registries.every((r) => deps.rgy.store.headEvent(r)?.ilk === "bup");
+}
+/** The v2 Grant behind `grant` and the local parties to it, or null when it is not a Grant this runtime is party to. */
+function grantParties(hby, grant) {
+    const db = hby.db, serder = db.exns.get([grant]) ?? db.epse.get([grant]);
+    if (!serder || serder.said !== grant || serder.route !== "/ipex/grant" || serder.pvrsn.major < 2)
+        return null;
+    const sender = serder.pre, recipient = serder.sad?.ri;
+    const issuer = typeof sender === "string" ? hby.habs.get(sender) : undefined;
+    const holder = typeof recipient === "string" ? hby.habs.get(recipient) : undefined;
+    return issuer || holder ? { serder, issuer, holder } : null;
+}
+/**
+ * Every pending Grant the stores prove a restarted process can finish: one scan of the pending exchange
+ * escrow, made once when the owner first runs. A pure read.
+ */
+function resumableGrants(deps) {
+    const found = [];
+    for (const [[grant]] of [...deps.hby.db.epse.getTopItemIter()]) {
+        const parties = grantParties(deps.hby, grant);
+        if (!parties)
+            continue;
+        if (parties.issuer && resumable(deps, parties.issuer, grant, "issuer")) {
+            found.push({ hab: parties.issuer, grant, role: "issuer" });
+        }
+        else if (parties.holder && resumable(deps, parties.holder, grant, "holder")) {
+            found.push({ hab: parties.holder, grant, role: "holder" });
+        }
+    }
+    return found;
+}
+/** The terminal reading of a pending Grant no process can complete: ended by a restart, or by another exchange. */
+function orphaned(deps, hab, grant) {
+    const credential = deps.exc.retainedInput(grant)?.nests?.[0]?.body;
+    const registry = credential instanceof SerderACDC ? credential.regid : undefined;
+    if (registry && hab.mgr.hasRegistryRoot(hab.pre, registry) && !registryUncommitted(deps.rgy.store, registry)) {
+        return ["interrupted", COMMITTED];
+    }
+    return ["interrupted", RESTARTED];
+}
+/**
+ * Sign a fresh Grant for `credential` and take it into local pending issuance
+ * without approving DH or generating a root. A host may deliver or file the
+ * returned wire itself and begin later with the Grant SAID.
+ */
+export function* prepareIssuanceGrant(ops, draft) {
+    const { deps, discloser } = ops, { credential, options } = draft;
+    const hab = credential.regid ? deps.rgy.regs.get(credential.regid)?.hab : undefined;
+    if (!hab)
+        throw new ValidationError("Fresh issuance requires the issuer's managed local registry");
+    requireIndividual(deps, hab);
+    hab.mgr.requireRegistryRootAccess();
+    const prepared = yield* discloser.prepareIssuanceGrantBody(hab.pre, credential, options);
+    const wire = concatBytes(discloser.proofSupport(prepared.raw, hab), exchangeWire(hab, prepared.exn, prepared.nests));
+    yield* deps.reactor.processBytes(wire, { local: true });
+    yield* deps.protocol.processEscrowsOnce();
+    const xid = grantTransactionId(prepared.exn);
+    if (!deps.exc.pendingGrant(prepared.exn.said, { xid, sender: hab.pre, recipient: options.recipient })) {
+        throw new ValidationError("Fresh Grant did not reach authenticated pending issuance");
+    }
+    return { grant: prepared.exn.said, wire };
+}
+function requireIndividual(deps, hab) {
+    if (isLocalGroupHab(deps.hby, hab)) {
+        throw new ValidationError("This finite issuance workflow requires an individual habitat; group issuance needs explicit member coordination");
+    }
+}
+/**
+ * The exact unanchored pending Grant a local party may consent to, with its deadline. Refuses a group
+ * identifier, an issuance already begun, a Grant that is not this party's, and an issuer without its registry.
+ */
+function selectGrant(ops, hab, grant, role, group = false) {
+    const { deps } = ops;
+    if (!group)
+        requireIndividual(deps, hab);
+    if (ops.live.has(grant) || deps.exc.complete(grant)) {
+        throw new ValidationError("Issuance was already begun for this Grant");
+    }
+    const retained = deps.exc.retainedInput(grant, { pending: true });
+    const credential = retained?.nests?.[0]?.body;
+    if (!retained || !(credential instanceof SerderACDC) || !credential.regid
+        || (role === "issuer" ? retained.serder.pre : retained.serder.sad.ri) !== hab.pre
+        || retained.sourceSeals?.length || retained.ptds?.length || retained.essrs?.length) {
+        throw new ValidationError("Select the exact unanchored pending issuance Grant for this local party");
+    }
+    const reg = deps.rgy.regs.get(credential.regid);
+    if (role === "issuer" && (!reg || reg.hab !== hab)) {
+        throw new ValidationError("Issuance requires the selected issuer's managed local registry");
+    }
+    const deadline = deps.exc.exchangeDeadline(retained.serder), expires = timestampMicros(deadline);
+    if (!deadline || expires === null)
+        throw new Error("Authenticated pending Grant has a missing or corrupt deadline");
+    return { retained, credential, deadline, expires };
+}
+/** The Grant body with its nested disclosure (the input of proof support) and the Grant as sent to the holder. */
+function* grantWires(retained) {
+    const raw = concatBytes(Counter.makeGVC(Vrsn_2_0), ...yield* call(() => Promise.all((retained.nests ?? []).map((nest) => collectPayload(framePayload(nest))))));
+    return { raw, grantWire: yield* storedExchangeWire(retained) };
+}
+/**
+ * The issuer's one "issue this credential" consent for a prepared Grant ({@link prepareIssuanceGrant}); the
+ * issuer is the Grant's sender. Approves the DH exchange, signs the query and records the
+ * authorisation, including the later KEL signature that anchors the registry
+ * update, in memory. Returns after local commit; `processOnce` does the rest.
+ *
+ * @throws ValidationError for a Grant that is not this identifier's exact
+ * unanchored pending issuance, an unmanaged registry, a group identifier, or
+ * an issuance already begun or completed.
+ */
+export function* beginIssuance(ops, grant, auths) {
+    const { deps } = ops, hab = grantParties(deps.hby, grant)?.issuer;
+    if (!hab)
+        throw new ValidationError("Select the exact unanchored pending issuance Grant for this local party");
+    const { retained, credential, deadline, expires } = selectGrant(ops, hab, grant, "issuer");
+    const { raw, grantWire } = yield* grantWires(retained);
+    const dh = deps.dhkes.dhke(hab), xid = dh.approve(grant), query = dh.start(grant);
+    ops.ended.delete(grant);
+    ops.live.set(grant, {
+        grant,
+        xid,
+        role: "issuer",
+        deadline,
+        hab,
+        dh,
+        peer: retained.serder.sad.ri,
+        registry: credential.regid,
+        expires,
+        issuer: { credential, raw, grantWire, query, auths, sent: false, nextQuery: 0 },
+        phase: "exchangingKeys",
+        outbox: new DeliveryOutbox(ops.deps.retry),
+        finished: false,
+        busy: false,
+    });
+    deps.changes?.push({ kind: "issuance", id: grant });
+    return { grant, xid };
+}
+/**
+ * The issuer's one consent to issue a fresh credential: signs the Grant ({@link prepareIssuanceGrant}) and begins
+ * the issuance ({@link beginIssuance}) in one step.
+ */
+export function* proposeIssuance(ops, draft, auths) {
+    return yield* beginIssuance(ops, (yield* prepareIssuanceGrant(ops, draft)).grant, auths);
+}
+/**
+ * Pure read of one issuance: what ended in this process, the live table, and otherwise what the protocol
+ * stores prove (see the module doc for the table and what a reload loses). A pending Grant no live
+ * operation holds reads `interrupted` (or `expired` once the Grant deadline has passed); that is a
+ * statement, not a write.
+ *
+ * @throws ValidationError when `grant` is not a v2 Grant this runtime's identifiers are party to.
+ */
+export function issuanceStatus(ops, grant) {
+    const { deps } = ops, ended = ops.ended.get(grant), live = ops.live.get(grant);
+    if (ended)
+        return { state: ended.state, role: ended.role, reason: ended.reason };
+    if (live && !reached(deps.clock, live.expires)) {
+        return {
+            state: "active",
+            role: live.role,
+            phase: live.phase,
+            deadline: live.deadline ?? undefined,
+            ...(live.outbox.failure && { failure: live.outbox.failure }),
+        };
+    }
+    const parties = grantParties(deps.hby, grant);
+    if (!parties)
+        throw new ValidationError("No issuance was begun for this Grant");
+    const { serder, issuer, holder } = parties, db = deps.hby.db;
+    if (deps.exc.complete(grant)) {
+        const admitted = !!db.erpy.get([grant]);
+        if (!holder || (issuer && !admitted))
+            return { state: "done", role: "issuer", phase: "issued" };
+        if (admitted)
+            return { state: "done", role: "holder", phase: "admitted" };
+        return { state: "active", role: "holder", phase: "awaitingAdmitConsent", needs: "admit" };
+    }
+    const role = issuer ? "issuer" : "holder", hab = (issuer ?? holder);
+    const group = isLocalGroupHab(deps.hby, hab);
+    // A group issuer's partial Grant has no accepted lifetime until its members' contributions authenticate it.
+    const lifetime = deps.exc.exchangeDeadline(serder) ?? undefined;
+    const deadline = lifetime, expires = lifetime ? timestampMicros(lifetime) : null;
+    if (!group && (!deadline || expires === null))
+        throw new ValidationError("No issuance was begun for this Grant");
+    if (reached(deps.clock, expires)) {
+        const credential = deps.exc.retainedInput(grant)?.nests?.[0]?.body;
+        const registry = credential instanceof SerderACDC ? credential.regid : undefined;
+        const late = role === "holder" && registry && deps.rgy.store.headEvent(registry)?.ilk === "bup";
+        return { state: "expired", role, reason: late ? EXPIRED_LATE : EXPIRED };
+    }
+    if (resumable(deps, hab, grant, role))
+        return { state: "active", role, phase: "rootRetained", deadline };
+    if ((role === "holder" || group) && !heldRoot(deps, hab, grant)) {
+        // A group issuer's Grant may still be a partial one that only its members' contributions authenticate.
+        if (!group && !deps.exc.retainedInput(grant, { pending: true })) {
+            throw new ValidationError("No issuance was begun for this Grant");
+        }
+        return { state: "active", role, phase: "awaitingExchangeConsent", needs: "exchange", deadline };
+    }
+    const [state, reason] = orphaned(deps, hab, grant);
+    return { state, role, reason };
+}
+/**
+ * Pure read of the Grants waiting for the holder's exchange consent: authenticated pending v2 Grants addressed
+ * to a local identifier (to `hab` when given) for which {@link approveIssuanceExchange} would be accepted.
+ * `issuanceStatus` throws for a Grant until it is stored; this lists the stored ones, so an embedder needs no poll.
+ */
+export function pendingIssuanceGrants(ops, { hab } = {}) {
+    const { deps } = ops, found = [];
+    for (const [[grant]] of [...deps.hby.db.epse.getTopItemIter()]) {
+        const holder = grantParties(deps.hby, grant)?.holder;
+        if (!holder || (hab && holder.pre !== hab.pre))
+            continue;
+        try {
+            const status = issuanceStatus(ops, grant);
+            if (status.state !== "active" || status.needs !== "exchange")
+                continue;
+            const { retained, credential, deadline } = selectGrant(ops, holder, grant, "holder");
+            found.push({
+                grant,
+                holder: holder.pre,
+                issuer: retained.serder.pre,
+                credential: credential.said,
+                registry: credential.regid,
+                deadline,
+            });
+        }
+        catch (error) {
+            // Not consentable (a group identifier, a Grant with sources): it is not pending for this holder.
+            if (!(error instanceof ValidationError))
+                throw error;
+        }
+    }
+    return found;
+}
+/**
+ * Pure read of the pending Grants addressed to a local group (to `group` when given) that its members have not
+ * consented to: authenticated pending v2 Grants whose issuance status reads `awaitingExchangeConsent`.
+ * {@link pendingIssuanceGrants} lists the individual identifiers' Grants and skips groups; this is its group form.
+ */
+export function pendingGroupGrants(ops, { group } = {}) {
+    const { deps } = ops, found = [];
+    for (const [[grant]] of [...deps.hby.db.epse.getTopItemIter()]) {
+        const parties = grantParties(deps.hby, grant), holder = parties?.holder;
+        if (!parties || !holder || !isLocalGroupHab(deps.hby, holder) || (group && holder.pre !== group.pre))
+            continue;
+        try {
+            const status = issuanceStatus(ops, grant);
+            if (status.state !== "active" || status.needs !== "exchange")
+                continue;
+            const credential = deps.exc.retainedInput(grant, { pending: true })?.nests?.[0]?.body;
+            const deadline = deps.exc.exchangeDeadline(parties.serder);
+            if (!(credential instanceof SerderACDC) || !credential.regid || !deadline)
+                continue;
+            found.push({
+                grant,
+                holder: holder.pre,
+                issuer: parties.serder.pre,
+                credential: credential.said,
+                registry: credential.regid,
+                deadline,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof ValidationError))
+                throw error;
+        }
+    }
+    return found;
+}
+/** Whether `hab` holds a registry root for the credential registry this Grant discloses. */
+function heldRoot(deps, hab, grant) {
+    const credential = deps.exc.retainedInput(grant)?.nests?.[0]?.body;
+    const registry = credential instanceof SerderACDC ? credential.regid : undefined;
+    return !!registry && hab.mgr.hasRegistryRoot(hab.pre, registry);
+}
+/**
+ * Observe until the issuance is done or ended, or the budget expires. Starts no
+ * worker and drives nothing: someone else must call `processOnce`.
+ */
+export function* waitForIssuance(ops, grant, { timeoutMs, clock = ops.deps.clock, until = (status) => status.state !== "active" }) {
+    // A phase is not reached while the step that produced it still owes a delivery: the host would stop its workers first.
+    const settled = yield* observeUntil(() => until(issuanceStatus(ops, grant)) && !ops.owes(grant), {
+        timeoutMs,
+        clock,
+    });
+    const status = issuanceStatus(ops, grant);
+    return settled ? { outcome: "settled", status } : { outcome: "timed-out", status, timeoutMs };
+}
+/**
+ * The holder's consent to the DH exchange for one pending Grant addressed to a local identifier. Approves DH and records the
+ * consent; `processOnce` then answers the issuer's query, waits for its registry update and finishes the Grant.
+ * Admitting the credential is a separate consent ({@link admitIssuance}).
+ */
+export function approveIssuanceExchange(ops, grant) {
+    const { deps } = ops, hab = grantParties(deps.hby, grant)?.holder;
+    if (!hab)
+        throw new ValidationError("Select the exact unanchored pending issuance Grant for this local party");
+    const { retained, credential, deadline, expires } = selectGrant(ops, hab, grant, "holder");
+    const dh = deps.dhkes.dhke(hab), xid = dh.approve(grant);
+    ops.ended.delete(grant);
+    ops.live.set(grant, {
+        grant,
+        xid,
+        role: "holder",
+        deadline,
+        hab,
+        dh,
+        peer: retained.serder.pre,
+        registry: credential.regid,
+        expires,
+        phase: "exchangingKeys",
+        outbox: new DeliveryOutbox(ops.deps.retry),
+        finished: false,
+        busy: false,
+    });
+    deps.changes?.push({ kind: "issuance", id: grant });
+    return { grant, xid };
+}
+/**
+ * The holder's consent to admit one accepted Grant: signs the Admit, accepts it locally and records it. Works for
+ * a Grant finished by this module and for any other accepted v2 Grant. Returns
+ * before delivery so an embedder can record its own inventory first; see {@link deliverIssuanceAdmit}.
+ *
+ * @throws ValidationError for a Grant that is not accepted and addressed to a local identifier, an admitted Grant, or a group identifier.
+ */
+export function* admitIssuance(deps, grant, options = {}) {
+    const { message = "", gvrsn, auths } = options, hab = grantParties(deps.hby, grant)?.holder;
+    if (!hab)
+        throw new ValidationError("Admit requires an accepted v2 Grant addressed to a local identifier");
+    if (deps.hby.db.erpy.get([grant]))
+        throw new ValidationError("Issuance cannot be admitted in its state");
+    const prepared = yield* new IpexAdmitter(deps.hby, deps.rgy.store, deps.exc).prepareAdmit(grant, hab.pre, {
+        consent: true,
+        auths,
+        message,
+        gvrsn,
+        receiptor: deps.receiptor,
+    });
+    const wire = concatBytes(prepared.support, prepared.wire);
+    yield* deps.reactor.processBytes(wire, { local: true });
+    yield* deps.protocol.processEscrowsOnce();
+    if (!deps.exc.complete(prepared.admit.said))
+        throw new ValidationError("Local ACDC v2 Admit was not accepted.");
+    deps.changes?.push({ kind: "issuance", id: grant });
+    return { admit: prepared.admit, src: hab.pre, wire, dest: prepared.admit.sad.ri };
+}
+/** Deliver an accepted Admit; needs the host's delivery worker. Returns the destinations reached. */
+export function* deliverIssuanceAdmit(delivery, admitted) {
+    return yield* delivery.deliver({ src: admitted.src, dest: admitted.dest, msg: admitted.wire });
+}
+/**
+ * Rebuild an Admit this process signed earlier so it can be delivered again, after a failed delivery or a
+ * restart. The wire is rebuilt from the stored signatures or source seal, so it is the bytes first made and
+ * nothing is signed. Delivery stays with {@link deliverIssuanceAdmit}. A peer that already took the Admit
+ * may drop the repeat as a replay.
+ *
+ * @throws ValidationError for an Admit no local identifier signed or whose retained factors no longer authenticate.
+ */
+export function* rebuildIssuanceAdmit(deps, admit) {
+    const retained = deps.exc.retainedInput(admit), serder = retained?.serder;
+    const hab = serder?.pre ? deps.hby.habs.get(serder.pre) : undefined;
+    if (!retained || !serder || serder.route !== "/ipex/admit" || !hab || typeof serder.sad?.ri !== "string") {
+        throw new ValidationError("No Admit was signed by a local identifier with this SAID");
+    }
+    const support = retained.sourceSeals?.length
+        ? new IpexDiscloser(deps.hby, deps.rgy.store, deps.exc, deps.receiptor).kel(hab)
+        : new Uint8Array();
+    return {
+        admit: serder,
+        src: hab.pre,
+        wire: concatBytes(support, yield* storedExchangeWire(retained)),
+        dest: serder.sad.ri,
+    };
+}
+/**
+ * Local abandon: release the DH approval (ephemeral keys, permanent refusal of
+ * this operation) and read `abandoned` until the process ends. Does not message the peer and does
+ * not undo a retained root or a registry update that was already anchored.
+ * Does nothing to an issuance that is already done or ended.
+ *
+ * @throws ValidationError when no issuance was begun for `grant`.
+ */
+export function abandonIssuance(ops, grant, reason = "Abandoned by the user") {
+    const status = issuanceStatus(ops, grant);
+    if (status.state !== "active")
+        return;
+    const live = ops.live.get(grant);
+    if (live)
+        ops.end(live, "abandoned", reason);
+    else {
+        ops.ended.set(grant, { role: status.role, state: "abandoned", reason });
+        ops.deps.changes?.push({ kind: "issuance", id: grant });
+    }
+}