keri-ts 2.1.0 → 2.2.0

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" };
+}

package/esm/keri/npm/src/app/identity/habbing.js

@@ -17,6 +17,7 @@ import { Deck } from "../../core/deck.js";
 import { TransIdxSigGroup } from "../../core/dispatch.js";
 import { ValidationError } from "../../core/errors.js";
 import { Kevery } from "../../core/kel/eventing.js";
+import { Kever } from "../../core/kel/kever.js";
 import { incept as inceptEvent, interact as interactEvent, query as queryEvent, receipt as receiptEvent, reply as replyEvent, rotate as rotateEvent, } from "../../core/protocol-eventing.js";
 import { messagize } from "../../core/protocol-serialization.js";
 import { HabitatRecord } from "../../core/records.js";
@@ -275,6 +276,23 @@ export class Hab {
     get accepted() {
         return !!this.pre && this.db.getKever(this.pre) !== null;
     }
+    /**
+     * Whether the held or stored signing keys currently allow this habitat to sign.
+     * False for a keyless habitat (`makeSignedHab`) until the host holds its signer.
+     */
+    canSign() {
+        try {
+            const probe = new Uint8Array(1);
+            if (this.kever?.transferable === false)
+                this.sign(probe, false);
+            else
+                this.sign(probe, true);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /** Return the live accepted-state `Kever` for this habitat when available. */
     get kever() {
         return this.pre ? this.db.getKever(this.pre) : null;
@@ -436,8 +454,24 @@ export class Hab {
         if (!pre || !serder.said) {
             throw new Error("Expected inception serder to provide string pre and said.");
         }
-        const opre = verfers[0].qb64;
-        this.mgr.move(opre, pre);
+        const sigs = this.mgr.sign(serder.raw, keys, true);
+        this.mgr.move(verfers[0].qb64, pre);
+        this.admitInception(serder, sigs, hidden);
+    }
+    /**
+     * Admit one signed inception as this habitat's first event: bind `pre`,
+     * register the name and habitat records unless `hidden`, and accept the event
+     * into the local KEL.
+     *
+     * Shared tail of `make()` and `makeSigned()`. It writes no keeper state and
+     * never signs. On rejection the `prefixes` entry is withdrawn and the error
+     * propagates; callers decide what else to undo.
+     */
+    admitInception(serder, sigers, hidden) {
+        const pre = serder.pre;
+        if (!pre || !serder.said) {
+            throw new Error("Expected inception serder to provide string pre and said.");
+        }
         this.pre = pre;
         if (!hidden) {
             const habord = new HabitatRecord({
@@ -449,9 +483,8 @@ export class Hab {
             this.db.pinName(this.ns ?? "", this.name, pre);
             this.db.prefixes.add(pre);
         }
-        const sigs = this.mgr.sign(serder.raw, keys, true);
         try {
-            this.acceptLocally(serder, sigs);
+            this.acceptLocally(serder, sigers);
         }
         catch (error) {
             if (!hidden) {
@@ -460,6 +493,50 @@ export class Hab {
             throw error;
         }
     }
+    /**
+     * Adopt a pre-signed inception this `Habery` did not generate, with no
+     * keeper key state for it (KERIpy `SignifyHab.incept` / `makeSignifyHab`).
+     *
+     * The inception is evaluated first, without mutation, by the same `Kever`
+     * decision local acceptance uses: SAID, prefix derivation, key and threshold
+     * material, and the signatures against the event's own keys. Anything but an
+     * accept (including an escrow for missing signatures) is refused before any
+     * record is written. A name or prefix already in use is refused too.
+     *
+     * Differences from KERIpy: verification precedes persistence instead of
+     * following it, a taken name is refused before anything is written (KERIpy
+     * pins the habitat record first), and `sign` is not disabled; it succeeds
+     * once the host holds the matching signer (`Manager.hold`).
+     */
+    makeSigned(args) {
+        const { serder, sigers, hidden = false } = args;
+        const pre = serder.pre;
+        if (!pre || !serder.said) {
+            throw new ValidationError("Pre-signed inception must provide a prefix and SAID.");
+        }
+        if (this.db.getHab(pre) || this.db.getKever(pre) || this.db.prefixes.has(pre)) {
+            throw new ValidationError(`Habitat prefix ${pre} already exists.`);
+        }
+        if (!hidden && this.db.getName(this.ns ?? "", this.name) !== null) {
+            throw new ValidationError(`Habitat name ${this.name} already exists.`);
+        }
+        const decision = Kever.evaluateInception({ db: this.db, serder, sigers, local: true });
+        if (decision.kind !== "accept") {
+            const detail = decision.kind === "duplicate" ? decision.duplicate : decision.message;
+            throw new ValidationError(`Pre-signed inception ${serder.said} refused: ${detail}`);
+        }
+        try {
+            this.admitInception(serder, sigers, hidden);
+        }
+        catch (error) {
+            if (!hidden) {
+                this.db.habs.rem(pre);
+                this.db.names.rem([this.ns ?? "", this.name]);
+            }
+            this.pre = "";
+            throw error;
+        }
+    }
     /**
      * Rotate this habitat through the shared accepted-state path.
      *
@@ -1190,6 +1267,17 @@ export class Habery {
             writable: true,
             value: void 0
         });
+        /**
+         * Prefixes of habitats whose alias config was not applied at open because they
+         * could not sign yet (a keyless habitat before the host holds its signer). The
+         * host calls `hab.reconfigure()` after holding; applying config is retried then.
+         */
+        Object.defineProperty(this, "deferredReconfigure", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
         this.storeOpener = opener;
         this.borrowsStores = borrowsStores;
         this.name = name;
@@ -1237,8 +1325,10 @@ export class Habery {
     /**
      * Populate the in-memory habitat cache from durable `habs.` + `states.` data.
      *
-     * Bare metadata records without corresponding accepted key state are skipped
-     * so `Habery.habs` only contains reopenable local habitats.
+     * Like KERIpy `loadHabs`, a local group record is held even while its
+     * inception is unaccepted: the `Hab` reads accepted state on demand, so it
+     * becomes usable the moment the event is accepted. A non-group record without
+     * accepted state is an orphan; `Baser.reloadKevers` already dropped it.
      */
     loadHabs() {
         this.reconfigure();
@@ -1251,13 +1341,20 @@ export class Habery {
             const hab = new Hab(habord.name, this.db, this.ks, this.mgr, this.cf, this.rtr, this.rvy, this.kevery, habord.domain, hid);
             if (!hab.accepted) {
                 if (habord.mid) {
+                    this.habs.set(hab.pre, hab);
                     continue;
                 }
                 throw new ValidationError(`Problem loading Hab pre=${hid} name=${habord.name} from db.`);
             }
             this.habs.set(hab.pre, hab);
         }
+        this.deferredReconfigure.length = 0;
         for (const hab of this.habs.values()) {
+            // Config replies are signed. A habitat that cannot sign yet applies them once its signer is held.
+            if (hab.accepted && hab.configuredSection() && !hab.canSign()) {
+                this.deferredReconfigure.push(hab.pre);
+                continue;
+            }
             hab.reconfigure();
         }
         // Restart recovery: commit members of an accepted establishment event
@@ -1327,6 +1424,32 @@ export class Habery {
             }
         }
     }
+    /**
+     * Adopt an inception the caller built and signed, creating a habitat with no
+     * keeper key state (KERIpy `makeSignifyHab`).
+     *
+     * Contract:
+     * - the inception and its signatures are verified before anything is
+     *   persisted; a bad, under-signed or duplicate inception is refused and
+     *   leaves no record behind
+     * - nothing is written to the keeper, so the hab cannot sign until the host
+     *   calls `mgr.hold()` with the matching signer(s), cannot rotate, and after
+     *   reopen is present again with signing unavailable until re-held
+     * - hold signers with the encoding the inception's keys use (`D...` for
+     *   transferable, `B...` for non-transferable)
+     * - unlike `makeHab`, bootstrap config replies are not applied, since they
+     *   need a signing key; the host reconfigures after holding
+     */
+    makeSignedHab(name, ns, args) {
+        const pre = args.serder.pre;
+        if (pre && this.habs.has(pre)) {
+            throw new ValidationError(`Habitat prefix ${pre} already exists.`);
+        }
+        const hab = new Hab(name, this.db, this.ks, this.mgr, this.cf, this.rtr, this.rvy, this.kevery, ns, "");
+        hab.makeSigned(args);
+        this.habs.set(hab.pre, hab);
+        return hab;
+    }
     /** Creates and caches a new habitat under this habery. */
     makeHab(name, ns, args = {}) {
         const hab = new Hab(name, this.db, this.ks, this.mgr, this.cf, this.rtr, this.rvy, this.kevery, ns, "");

package/esm/keri/npm/src/app/identity/keeping.js

@@ -241,6 +241,16 @@ export class Manager {
             writable: true,
             value: null
         });
+        /**
+         * Borrowed, volatile signers keyed by qualified public key (`hold()`).
+         * Never written to the Keeper and never consulted by `Keeper` rows.
+         */
+        Object.defineProperty(this, "held", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         const { ks, seed = "", aeid = "", pidx = 0, algo = Algos.salty, salt = randomSaltQb64(), tier = Tiers.low, } = args;
         this._ks = ks;
         this._seed = seed;
@@ -428,13 +438,21 @@ export class Manager {
         }
         return root;
     }
-    /** Retain once, returning false for the identical root without replacing ciphertext. */
-    putRegistryRoot(aid, regid, root) {
+    /**
+     * Retain once, returning false for the identical root without replacing ciphertext. `overwrite` replaces a
+     * different held root; only a caller that has shown that root was never used (no update staged or accepted
+     * for its registry) may set it.
+     */
+    putRegistryRoot(aid, regid, root, overwrite = false) {
         const keys = this.registryRootKeys(aid, regid);
         if (!(root instanceof Salter) || root.code !== MtrDex.Salt_128)
             throw new Error("Registry root must be Salt128");
         const { aeid, encrypter, decrypter } = this.registryRootCrypto();
-        return this.ks.retainRegistryRoot(keys, root, aeid, encrypter, decrypter);
+        return this.ks.retainRegistryRoot(keys, root, aeid, encrypter, decrypter, overwrite);
+    }
+    /** Whether a root is retained for `aid` and `regid`; reads no ciphertext and needs no unlocked Keeper. */
+    hasRegistryRoot(aid, regid) {
+        return !!this.ks.rroots.get(this.registryRootKeys(aid, regid));
     }
     signerDecrypter() {
         if (this.aeid && !this.decrypter) {
@@ -442,8 +460,63 @@ export class Manager {
         }
         return this.decrypter ?? undefined;
     }
-    /** Load one managed signer seed by its public verifier key. */
+    /**
+     * Borrow live signers for signing, decryption and ESSR opening without
+     * persisting them.
+     *
+     * Held signers are consulted before stored keys by the one private lookup
+     * every `sign`, `decrypt`, `open`, group-member and endpoint-role path
+     * resolves through. They live only in this `Manager` instance's memory:
+     * nothing is written to any Keeper table, re-encryption by `updateAeid()`
+     * neither reads nor changes them, and a new `Manager` over the same Keeper
+     * starts with none.
+     *
+     * Contract:
+     * - The table is keyed by `signer.verfer.qb64`. The same raw key encodes
+     *   differently when transferable (`D...`) and non-transferable (`B...`), so
+     *   build each `Signer` with the transferability the key list or prefix uses,
+     *   and hold that encoding. A request for the other encoding does not match.
+     * - The host owns each `Signer` and its seed bytes, including zeroing them.
+     *   This keeps the reference only; it never copies seed bytes and never
+     *   erases them. Dropping a reference with `release()` does not zero memory.
+     * - Holding a pub that is already held replaces the earlier signer. A held
+     *   signer shadows a stored key with the same public key.
+     * - The `pre/path` branch of `sign()` re-derives salty keys from the stored
+     *   prefix salt and never consults held signers.
+     *
+     * @param signers Signers to borrow; all are validated before any is held.
+     */
+    hold(signers) {
+        const batch = new Map();
+        for (const signer of signers) {
+            if (!(signer instanceof Signer)) {
+                throw new ValidationError("Held signers must be Signer instances");
+            }
+            batch.set(signer.verfer.qb64, signer);
+        }
+        for (const [pub, signer] of batch)
+            this.held.set(pub, signer);
+    }
+    /**
+     * Drop held signer references: all of them, or only those for `pubs`.
+     *
+     * Unheld pubs are ignored. Afterwards a request for a released key resolves
+     * from stored keys only and fails as any missing key does. This drops
+     * references; zeroing a signer's seed stays the host's job.
+     */
+    release(pubs) {
+        if (pubs === undefined) {
+            this.held.clear();
+            return;
+        }
+        for (const pub of pubs)
+            this.held.delete(pub);
+    }
+    /** Resolve one signer by qualified public key: held first, then the Keeper's `pris.`. */
     getSignerByPub(pub) {
+        const held = this.held.get(pub);
+        if (held)
+            return held;
         const signer = this.ks.pris.get(pub, this.signerDecrypter());
         if (!signer) {
             throw new Error(`Missing prikey in db for pubkey=${pub}`);