keri-ts 2.0.1 → 2.2.0

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

@@ -17,19 +17,20 @@ 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";
 import { Roles } from "../../core/roles.js";
 import { BasicReplyRouteHandler, Revery, Router } from "../../core/routing.js";
 import { Schemes } from "../../core/schemes.js";
-import { createBaser } from "../../db/basing.js";
-import { createKeeper, PreSit } from "../../db/keeping.js";
+import { Baser } from "../../db/basing.js";
+import { openOwner } from "../../db/core/store-owner.js";
+import { Keeper, PreSit } from "../../db/keeping.js";
 import { makeNowIso8601 } from "../../time/mod.js";
 import { oobiReplyMessages } from "../bootstrap/oobi-replies.js";
 import { loadStoredReply } from "../delivery/stored-replies.js";
 import { acceptedGroupMembers, latestGroupContribution } from "../multisig/group-members.js";
-import { createConfiger } from "./configing.js";
 import { branToSaltQb64, encodeHugeNumber, ensureKeeperCryptoReady, Manager, normalizeSaltQb64, saltySigner, } from "./keeping.js";
 /** Reserved alias for the local signatory habitat record. */
 export const SIGNER = "__signatory__";
@@ -43,13 +44,16 @@ const KERI_V1 = Object.freeze({ major: 1, minor: 0 });
 /**
  * Select the KERI version for a new event on an existing identifier.
  *
- * An identifier keeps the KERI version of its accepted KEL, so rotation and
- * interaction never mix versions within one KEL. An explicit selection that
- * conflicts with the accepted KEL is refused rather than silently ignored.
+ * An identifier follows the KERI version of its latest accepted event. An explicit
+ * selection that conflicts with it is refused rather than silently ignored, except
+ * for a deliberate upgrade rotation, which is how a v1 identifier moves up to v2.
+ * Stricter than KERIpy, whose per-event default can mix versions without being asked.
  */
-function acceptedKelVersion(kever, requested) {
+function acceptedKelVersion(kever, requested, { allowUpgrade = false } = {}) {
     const accepted = kever.serder.pvrsn.major === 1 ? Vrsn_1_0 : Vrsn_2_0;
     if (requested && (requested.major !== accepted.major || requested.minor !== accepted.minor)) {
+        if (allowUpgrade && requested.major > accepted.major)
+            return requested;
         throw new ValidationError(`KEL of ${kever.prefixer.qb64} is KERI ${accepted.major}.${accepted.minor}; `
             + `refusing a KERI ${requested.major}.${requested.minor} event.`);
     }
@@ -272,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;
@@ -433,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({
@@ -446,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) {
@@ -457,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.
      *
@@ -473,7 +553,7 @@ export class Hab {
         if (!kever) {
             throw new ValidationError(`Missing accepted key state for ${this.pre}.`);
         }
-        const version = acceptedKelVersion(kever, args.version);
+        const version = acceptedKelVersion(kever, args.version, { allowUpgrade: true });
         const priorSit = this.ks.getSits(this.pre);
         if (!priorSit) {
             throw new ValidationError(`Missing keeper state for ${this.pre}.`);
@@ -1077,7 +1157,7 @@ export class Signator {
  */
 export class Habery {
     /** Compose one habery from already-opened storage, manager, and config surfaces. */
-    constructor(name, base, temp, headDirPath, compat, readonly, db, ks, mgr, cf, skipSignator = false) {
+    constructor(name, base, temp, headDirPath, compat, readonly, db, ks, mgr, cf, skipSignator = false, opener, borrowsStores = false) {
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
@@ -1114,6 +1194,19 @@ export class Habery {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "storeOpener", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** True when `db` and `ks` were borrowed; their owner closes them. */
+        Object.defineProperty(this, "borrowsStores", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "db", {
             enumerable: true,
             configurable: true,
@@ -1174,6 +1267,19 @@ 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;
         this.base = base;
         this.temp = temp;
@@ -1219,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();
@@ -1233,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
@@ -1309,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, "");
@@ -1688,10 +1829,20 @@ export class Habery {
         this.habs.set(pre, hab);
         return hab;
     }
-    /** Closes backing databases and optionally clears temp storage. */
+    /** Creates this Habery's sidecar stores. */
+    get opener() {
+        if (!this.storeOpener)
+            throw new ValidationError("This Habery was given stores without an opener for sidecars.");
+        return this.storeOpener;
+    }
+    /** Identity shared by this Habery's stores and sidecars. */
+    storeIdentity() {
+        return { name: this.name, base: this.base, temp: this.temp, reopen: true, readonly: this.readonly };
+    }
+    /** Closes owned backing databases and optionally clears temp storage. */
     *close(clear = false) {
         const failures = [];
-        const closing = [this.db.close(clear), this.ks.close(clear)];
+        const closing = this.borrowsStores ? [] : [this.db.close(clear), this.ks.close(clear)];
         if (this.cf)
             closing.push(this.cf.close(clear && this.temp));
         for (const operation of closing) {
@@ -1726,38 +1877,29 @@ export function branToSeedAeid(bran) {
  * The returned `Habery` immediately reconstructs its local habitat cache from
  * durable DB state rather than depending on process-local creation history.
  */
-export function* createHabery(args) {
-    const { name, base = "", temp = false, headDirPath, compat = false, readonly = false, cf: providedCf, skipConfig = false, skipSignator = false, bran, seed, aeid, salt, algo, } = args;
+export function* openHabery(args) {
+    const { name, base = "", temp = false, headDirPath, compat = false, readonly = false, cf: providedCf, createConfig, skipConfig = false, skipSignator = false, opener, stores, bran, seed, aeid, salt, algo, } = args;
     let db;
     let ks;
     let cf;
     let delivered = false;
     let failure;
     try {
-        db = yield* createBaser({
-            name,
-            base,
-            temp,
-            headDirPath,
-            compat,
-            reopen: true,
-            readonly,
-        });
-        ks = yield* createKeeper({
-            name,
-            base,
-            temp,
-            headDirPath,
-            compat,
-            reopen: true,
-            readonly,
-        });
+        if (!opener && !stores)
+            throw new ValidationError("A Habery needs a store opener or borrowed stores.");
+        if (!providedCf && !skipConfig && !createConfig) {
+            throw new ValidationError("A Habery needs a Configer, a Configer factory or skipConfig.");
+        }
+        const identity = { name, base, temp, reopen: true, readonly };
+        db = stores?.db ?? (yield* openOwner(new Baser(opener.create(Baser.Family, identity)), "Baser", identity));
+        ks = stores?.ks ?? (yield* openOwner(new Keeper(opener.create(Keeper.Family, identity)), "Keeper", identity));
         cf = providedCf
-            ?? (skipConfig ? undefined : (yield* createConfiger({
+            ?? (skipConfig ? undefined : (yield* createConfig({
                 name,
                 base,
                 temp,
                 headDirPath,
+                compat,
                 reopen: true,
                 clear: false,
             })));
@@ -1779,7 +1921,7 @@ export function* createHabery(args) {
             algo,
             salt: normalizeSaltQb64(salt),
         });
-        const hby = new Habery(name, base, temp, headDirPath, compat, readonly, db, ks, mgr, cf, skipSignator);
+        const hby = new Habery(name, base, temp, headDirPath, compat, readonly, db, ks, mgr, cf, skipSignator, opener, !!stores);
         delivered = true;
         return hby;
     }
@@ -1796,9 +1938,9 @@ export function* createHabery(args) {
             const closing = [];
             if (cf && cf !== providedCf)
                 closing.push(cf.close());
-            if (ks)
+            if (ks && !stores)
                 closing.push(ks.close());
-            if (db)
+            if (db && !stores)
                 closing.push(db.close());
             for (const operation of closing) {
                 try {

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}`);
@@ -1195,7 +1268,7 @@ export function b64DecodeUrl(text) {
 /**
  * Backward-compatibility no-op for older app-layer startup seams.
  *
- * CESR primitives now own libsodium readiness through their own module
+ * CESR primitives now own crypto backend readiness through their own module
  * initialization, so higher layers no longer need an explicit keeper-crypto
  * readiness step.
  */

package/esm/keri/npm/src/app/identity/lmdb-habery.js

@@ -0,0 +1,12 @@
+/** Default LMDB-backed `Habery` construction, kept apart so `openHabery` stays backend-neutral. */
+import { LmdbStoreOpener } from "../../db/core/lmdb-opener.js";
+import { createConfiger } from "./configing.js";
+import { openHabery } from "./habbing.js";
+/** Open a `Habery` on LMDB at its established paths, unless the caller supplies stores or an opener. */
+export function* createHabery(args) {
+    return yield* openHabery({
+        opener: new LmdbStoreOpener({ headDirPath: args.headDirPath, compat: args.compat }),
+        createConfig: createConfiger,
+        ...args,
+    });
+}