keri-ts 2.0.1 → 2.2.0

package/esm/keri/npm/src/db/keeping.js

@@ -2,7 +2,7 @@ import { Cipher, MtrDex, NumberPrimitive, Prefixer, Salter, Signer, Verfer, } fr
 import { DatabaseNotOpenError, DatabaseOperationError } from "../core/errors.js";
 import { consoleLogger } from "../core/logger.js";
 import { RawRecord } from "../core/records.js";
-import { LMDBer } from "./core/lmdber.js";
+import { StoreOwner } from "./core/store-owner.js";
 import { Komer } from "./koming.js";
 import { CatCesrIoSetSuber, CesrSuber, CryptSignerSuber, Suber } from "./subing.js";
 /**
@@ -101,14 +101,9 @@ function reencryptSalt(salt, encrypter, decrypter) {
  *   named handles
  * - compatibility mode supports KERIpy `.keri/ks` layout visibility
  */
-export class Keeper {
-    constructor(options = {}) {
-        Object.defineProperty(this, "lmdber", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
+export class Keeper extends StoreOwner {
+    constructor(store, logger = consoleLogger) {
+        super(store);
         Object.defineProperty(this, "logger", {
             enumerable: true,
             configurable: true,
@@ -192,42 +187,7 @@ export class Keeper {
             writable: true,
             value: void 0
         });
-        this.logger = options.logger ?? consoleLogger;
-        const compat = options.compat ?? false;
-        this.lmdber = new LMDBer(options, {
-            tailDirPath: Keeper.TailDirPath,
-            cleanTailDirPath: "keri/clean/ks",
-            altTailDirPath: compat
-                ? Keeper.CompatAltTailDirPath
-                : Keeper.AltTailDirPath,
-            altCleanTailDirPath: compat ? ".keri/clean/ks" : ".tufa/clean/ks",
-            tempPrefix: Keeper.TempPrefix,
-            maxNamedDBs: Keeper.MaxNamedDBs,
-        });
-    }
-    /** Expose the resolved keeper database name delegated from the root LMDBer. */
-    get name() {
-        return this.lmdber.name;
-    }
-    /** Expose the resolved keeper base prefix delegated from the root LMDBer. */
-    get base() {
-        return this.lmdber.base;
-    }
-    /** Report whether the keeper LMDB environment and named subdb surface are open. */
-    get opened() {
-        return this.lmdber.opened;
-    }
-    /** Report whether the keeper environment is opened in read-only mode. */
-    get readonly() {
-        return this.lmdber.readonly;
-    }
-    /** Report whether this keeper uses a temporary backing directory. */
-    get temp() {
-        return this.lmdber.temp;
-    }
-    /** Expose the resolved filesystem path for the keeper environment, when open. */
-    get path() {
-        return this.lmdber.path;
+        this.logger = logger;
     }
     /**
      * Reopen the keeper environment and bind the KERIpy-style named subdbs.
@@ -238,7 +198,7 @@ export class Keeper {
      * flows have not yet exercised it deeply.
      */
     *reopen(options = {}) {
-        const opened = yield* this.lmdber.reopen(options);
+        const opened = yield* this.store.reopen(options);
         if (!opened)
             return false;
         try {
@@ -246,62 +206,62 @@ export class Keeper {
             // `aeid` anchors the encrypter/decrypter used to protect salts and
             // private keys, while `pidx`, `algo`, `salt`, and `tier` capture the
             // default root key-management settings.
-            this.gbls = new Suber(this.lmdber, { subkey: "gbls." });
+            this.gbls = new Suber(this.store, { subkey: "gbls." });
             // Public-key to private-key secret material store.
             // Keys are fully qualified public keys and values are the corresponding
             // fully qualified private keys.
-            this.pris = new CryptSignerSuber(this.lmdber, { subkey: "pris." });
+            this.pris = new CryptSignerSuber(this.store, { subkey: "pris." });
             // Group signing member tuples for one multisig prefix.
             // The stored tuple shape mirrors KERIpy's `(Prefixer, Number)` member
             // identifier set used by GroupSignifyHab flows.
-            this.smids = new CatCesrIoSetSuber(this.lmdber, {
+            this.smids = new CatCesrIoSetSuber(this.store, {
                 subkey: "smids.",
                 ctor: [Prefixer, NumberPrimitive],
             });
             // Group rotating member tuples for one multisig prefix.
             // The stored tuple shape mirrors KERIpy's `(Prefixer, Number)` member
             // identifier set used by GroupSignifyHab flows.
-            this.rmids = new CatCesrIoSetSuber(this.lmdber, {
+            this.rmids = new CatCesrIoSetSuber(this.store, {
                 subkey: "rmids.",
                 ctor: [Prefixer, NumberPrimitive],
             });
             // Prefix index keyed by the first public key in a key sequence.
             // Values are the identifier prefix, or the first public key for
             // temporary prefixes, matching the KERIpy keeper index contract.
-            this.pres = new CesrSuber(this.lmdber, {
+            this.pres = new CesrSuber(this.store, {
                 subkey: "pres.",
                 ctor: Prefixer,
             });
             // Root derivation parameters for one managed identifier prefix.
-            this.prms = new Komer(this.lmdber, {
+            this.prms = new Komer(this.store, {
                 subkey: "prms.",
                 recordClass: PrePrm,
             });
             // Old/current/next key situation for one managed identifier prefix.
-            this.sits = new Komer(this.lmdber, {
+            this.sits = new Komer(this.store, {
                 subkey: "sits.",
                 recordClass: PreSit,
             });
             // Replayable public-key sets keyed by `(prefix, ridx)`.
             // This enables lookup of the current signing keys after each rotation so
             // establishment events can be replayed in order.
-            this.pubs = new Komer(this.lmdber, {
+            this.pubs = new Komer(this.store, {
                 subkey: "pubs.",
                 recordClass: PubSet,
             });
             // Encrypted next private keys used by group-signify keeper flows.
             // KERIpy notes these are not yet broadly exercised outside that path.
-            this.prxs = new CesrSuber(this.lmdber, {
+            this.prxs = new CesrSuber(this.store, {
                 subkey: "prxs.",
                 ctor: Cipher,
             });
             // Encrypted next-key commitments used by group-signify keeper flows.
             // KERIpy notes these are not yet broadly exercised outside that path.
-            this.nxts = new CesrSuber(this.lmdber, {
+            this.nxts = new CesrSuber(this.store, {
                 subkey: "nxts.",
                 ctor: Cipher,
             });
-            this.rroots = new CesrSuber(this.lmdber, { subkey: "rroots.", ctor: Cipher });
+            this.rroots = new CesrSuber(this.store, { subkey: "rroots.", ctor: Cipher });
             return true;
         }
         catch (error) {
@@ -311,7 +271,7 @@ export class Keeper {
     }
     /** Close the underlying keeper LMDB environment. */
     *close(clear = false) {
-        return yield* this.lmdber.close(clear);
+        return yield* this.store.close(clear);
     }
     /**
      * Read one keeper-global string value from `gbls.`.
@@ -337,13 +297,12 @@ export class Keeper {
     changeEncryption({ currentAeid, aeid, encrypter, decrypter }) {
         if (this.readonly)
             throw new DatabaseOperationError("Cannot change encryption in a read-only keeper");
-        const env = this.lmdber.env;
-        if (!env)
+        if (!this.store.opened)
             throw new DatabaseNotOpenError("Keeper environment is not open");
-        if (this.lmdber.inWriteTransaction) {
+        if (this.store.inWriteTransaction) {
             throw new DatabaseOperationError("Keeper encryption change must own its write transaction");
         }
-        env.transactionSync(() => {
+        this.store.transaction(() => {
             const storedAeid = this.getGbls("aeid");
             if ((storedAeid ?? "") !== currentAeid) {
                 throw new DatabaseOperationError("Keeper AEID changed before encryption migration; reopen the manager");
@@ -384,21 +343,29 @@ export class Keeper {
                 throw new DatabaseOperationError("Keeper AEID write failed");
         });
     }
-    /** Retain an immutable root under the authenticated policy, owning its commit. */
-    retainRegistryRoot(keys, root, currentAeid, encrypter, decrypter) {
+    /**
+     * Retain a root under the authenticated policy, owning its commit. Immutable unless `overwrite`, which the
+     * caller sets only for a root it has established was never used; the old root then stays until this write.
+     */
+    retainRegistryRoot(keys, root, currentAeid, encrypter, decrypter, overwrite = false) {
         if (this.readonly)
             throw new DatabaseOperationError("Cannot retain registry roots in a read-only keeper");
-        const env = this.lmdber.env;
-        if (!env)
+        if (!this.store.opened)
             throw new DatabaseNotOpenError("Keeper environment is not open");
-        if (this.lmdber.inWriteTransaction) {
+        if (this.store.inWriteTransaction) {
             throw new DatabaseOperationError("Registry root retention must own its write transaction");
         }
-        return env.transactionSync(() => {
+        return this.store.transaction(() => {
             if (this.getGbls("aeid") !== currentAeid) {
                 throw new DatabaseOperationError("Keeper AEID changed before registry root retention; reopen the manager");
             }
             const old = this.rroots.get(keys);
+            if (old && overwrite) {
+                if (!this.rroots.pin(keys, encrypter.encrypt({ prim: root }))) {
+                    throw new DatabaseOperationError("Keeper registry root write failed");
+                }
+                return true;
+            }
             if (old) {
                 const retained = decrypter.decrypt({ cipher: old, ctor: Salter });
                 if (retained.qb64 !== root.qb64) {
@@ -520,29 +487,12 @@ export class Keeper {
         return this.rmids.get(pre);
     }
 }
-Object.defineProperty(Keeper, "TailDirPath", {
+/** Placement of this store kind. */
+Object.defineProperty(Keeper, "Family", {
     enumerable: true,
     configurable: true,
     writable: true,
-    value: "keri/ks"
-});
-Object.defineProperty(Keeper, "AltTailDirPath", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: ".tufa/ks"
-});
-Object.defineProperty(Keeper, "CompatAltTailDirPath", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: ".keri/ks"
-});
-Object.defineProperty(Keeper, "TempPrefix", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: "keri_ks_"
+    value: { tail: "ks", maxTables: 24 }
 });
 Object.defineProperty(Keeper, "MaxNamedDBs", {
     enumerable: true,
@@ -550,38 +500,3 @@ Object.defineProperty(Keeper, "MaxNamedDBs", {
     writable: true,
     value: 24
 });
-/** Constructor-safe async factory for a fully reopened `Keeper`. */
-export function* createKeeper(options = {}) {
-    const keeper = new Keeper(options);
-    let delivered = false;
-    let failure;
-    try {
-        const opened = yield* keeper.reopen(options);
-        if (!opened) {
-            throw new DatabaseNotOpenError("Failed to open Keeper");
-        }
-        delivered = true;
-        return keeper;
-    }
-    catch (error) {
-        failure = { error };
-        throw error;
-    }
-    finally {
-        if (!delivered) {
-            try {
-                yield* keeper.close();
-            }
-            catch (error) {
-                if (failure) {
-                    // deno-lint-ignore no-unsafe-finally -- Preserve the operation failure alongside shutdown failure.
-                    throw new AggregateError([failure.error, error], "Database acquisition and close failed", {
-                        cause: failure.error,
-                    });
-                }
-                // deno-lint-ignore no-unsafe-finally -- A shutdown failure must propagate.
-                throw error;
-            }
-        }
-    }
-}

package/esm/keri/npm/src/db/koming.js

@@ -88,7 +88,7 @@ export class KomerBase {
             value: void 0
         });
         this.db = db;
-        this.sdb = this.db.openDB(subkey, dupsort);
+        this.sdb = this.db.openTable(subkey, { dupsort });
         this.sep = sep;
         this.kind = assertKomerKind(kind);
         this.recordClass = recordClass;

package/esm/keri/npm/src/db/lmdb-stores.js

@@ -0,0 +1,68 @@
+/**
+ * LMDB-backed construction of the domain stores.
+ *
+ * These helpers bind each `StoreOwner` to an `LMDBer` at its established paths.
+ * Everything here reaches the native addon; backend-neutral callers use the
+ * store classes with an injected `DBer` instead.
+ */
+import { RegBaser } from "../acdc/regbasing.js";
+import { adoptRegistry } from "../acdc/registering.js";
+import { ValidationError } from "../core/errors.js";
+import { Baser } from "./basing.js";
+import { lmdbDefaultsFor } from "./core/lmdb-opener.js";
+import { LMDBer } from "./core/lmdber.js";
+import { openOwner } from "./core/store-owner.js";
+import { Keeper } from "./keeping.js";
+import { Mailboxer } from "./mailbox/mailboxing.js";
+import { Noter } from "./noting.js";
+import { Reger } from "./reger.js";
+/** Construct a closed LMDB-backed `Baser` at its established paths. */
+export function lmdbBaser({ compat, ...options } = {}) {
+    return new Baser(new LMDBer(options, lmdbDefaultsFor(Baser.Family, compat)), options.logger);
+}
+/** Constructor-safe async factory for a fully reopened `Baser`. */
+export function* createBaser(options = {}) {
+    return yield* openOwner(lmdbBaser(options), "Baser", options);
+}
+/** Construct a closed LMDB-backed `Keeper` at its established paths. */
+export function lmdbKeeper({ compat, ...options } = {}) {
+    return new Keeper(new LMDBer(options, lmdbDefaultsFor(Keeper.Family, compat)), options.logger);
+}
+/** Constructor-safe async factory for a fully reopened `Keeper`. */
+export function* createKeeper(options = {}) {
+    return yield* openOwner(lmdbKeeper(options), "Keeper", options);
+}
+/** Construct a closed LMDB-backed `Noter` at its established paths. */
+export function lmdbNoter({ compat, ...options } = {}) {
+    return new Noter(new LMDBer(options, lmdbDefaultsFor(Noter.Family, compat)));
+}
+/** Open a notification sidecar and return the ready-to-use databaser. */
+export function* createNoter(options = {}) {
+    return yield* openOwner(lmdbNoter(options), "Noter", options);
+}
+/** Construct a closed LMDB-backed `Mailboxer` at its established paths. */
+export function lmdbMailboxer({ compat, ...options } = {}) {
+    return new Mailboxer(new LMDBer(options, lmdbDefaultsFor(Mailboxer.Family, compat)));
+}
+/**
+ * Open a mailbox environment and return the ready-to-use databaser.
+ *
+ * Compatibility rule:
+ * - explicit mailbox opens stay strict
+ * - missing additive sidecars are tolerated only by higher-level habery open
+ *   flows that are inspecting compat stores readonly
+ */
+export function* createMailboxer(options = {}) {
+    return yield* openOwner(lmdbMailboxer(options), "Mailboxer", options);
+}
+/** Transfer a ready `Reger` to its caller, closing unreturned acquisitions on failure or cancellation. */
+export function* createReger({ compat, ...options } = {}) {
+    const store = new LMDBer(options, lmdbDefaultsFor(Reger.Family, compat));
+    return yield* openOwner(new Reger(store), "Reger", options);
+}
+/** Open a registry store on LMDB at its established paths; the reference web backend remains unsupported. */
+export function* openLmdbRegistry({ web = false, reopen = true, compat, opener: _opener, ...options } = {}) {
+    if (web)
+        throw new ValidationError("web registry backend is not yet supported by V2 Regery");
+    return yield* adoptRegistry(new RegBaser(new LMDBer(options, lmdbDefaultsFor(RegBaser.Family, compat))), reopen);
+}

package/esm/keri/npm/src/db/lmdb.js

@@ -0,0 +1,6 @@
+/** LMDB backend surface: native stores, paths and the default opener. */
+export { createHabery } from "../app/identity/lmdb-habery.js";
+export * from "./core/lmdb-opener.js";
+export * from "./core/lmdber.js";
+export * from "./core/path-manager.js";
+export * from "./lmdb-stores.js";

package/esm/keri/npm/src/db/mailbox/mailboxing.js

@@ -15,7 +15,7 @@
  */
 import { Diger, MtrDex } from "cesr-ts";
 import { DatabaseNotOpenError } from "../../core/errors.js";
-import { LMDBer } from "../core/lmdber.js";
+import { StoreOwner } from "../core/store-owner.js";
 import { CesrOnSuber, Suber } from "../subing.js";
 /** Raw-byte value family used for stored mailbox message bodies. */
 class BytesSuber extends Suber {
@@ -39,19 +39,9 @@ class BytesSuber extends Suber {
  * - `.tpcs` stores `(topic, on) -> digest`
  * - `.msgs` stores `digest -> raw message bytes`
  */
-export class Mailboxer extends LMDBer {
-    constructor(options = {}) {
-        const compat = options.compat ?? false;
-        super(options, {
-            tailDirPath: Mailboxer.TailDirPath,
-            cleanTailDirPath: "keri/clean/mbx",
-            altTailDirPath: compat
-                ? Mailboxer.CompatAltTailDirPath
-                : Mailboxer.AltTailDirPath,
-            altCleanTailDirPath: compat ? ".keri/clean/mbx" : ".tufa/clean/mbx",
-            tempPrefix: Mailboxer.TempPrefix,
-            maxNamedDBs: Mailboxer.MaxNamedDBs,
-        });
+export class Mailboxer extends StoreOwner {
+    constructor() {
+        super(...arguments);
         Object.defineProperty(this, "tpcs", {
             enumerable: true,
             configurable: true,
@@ -69,12 +59,12 @@ export class Mailboxer extends LMDBer {
      * Reopen the mailbox environment and bind the KERIpy-shaped named subdbs.
      */
     *reopen(options = {}) {
-        const opened = yield* super.reopen(options);
+        const opened = yield* this.store.reopen(options);
         if (!opened) {
             return false;
         }
-        this.tpcs = new CesrOnSuber(this, { subkey: "tpcs.", ctor: Diger });
-        this.msgs = new BytesSuber(this, { subkey: "msgs." });
+        this.tpcs = new CesrOnSuber(this.store, { subkey: "tpcs.", ctor: Diger });
+        this.msgs = new BytesSuber(this.store, { subkey: "msgs." });
         return true;
     }
     /**
@@ -119,15 +109,14 @@ export class Mailboxer extends LMDBer {
      * one transaction; false publication is an invariant failure, not a duplicate.
      */
     storeMsg(topic, msg) {
-        const env = this.env;
-        if (!env)
+        if (!this.opened)
             throw new DatabaseNotOpenError("Mailbox environment is not open");
         const raw = typeof msg === "string" ? new TextEncoder().encode(msg) : msg;
         const dig = new Diger({
             raw: Diger.digest(raw, MtrDex.Blake3_256),
             code: MtrDex.Blake3_256,
         });
-        return env.transactionSync(() => {
+        return this.transaction(() => {
             const on = this.appendToTopic(topic, dig);
             if (!Number.isSafeInteger(on) || on < 0)
                 throw new Error("Mailbox topic publication failed");
@@ -152,52 +141,10 @@ export class Mailboxer extends LMDBer {
         }
     }
 }
-/** Default primary path for Tufa-owned mailbox environments. */
-Object.defineProperty(Mailboxer, "TailDirPath", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: "keri/mbx"
-});
-/** Default alternate path for Tufa-owned mailbox environments. */
-Object.defineProperty(Mailboxer, "AltTailDirPath", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: ".tufa/mbx"
-});
-/** Alternate path used when opening KERIpy-compatible mailbox stores. */
-Object.defineProperty(Mailboxer, "CompatAltTailDirPath", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: ".keri/mbx"
-});
-Object.defineProperty(Mailboxer, "TempPrefix", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: "keri_mbx_"
-});
-Object.defineProperty(Mailboxer, "MaxNamedDBs", {
+/** Placement of this store kind. */
+Object.defineProperty(Mailboxer, "Family", {
     enumerable: true,
     configurable: true,
     writable: true,
-    value: 8
+    value: { tail: "mbx", maxTables: 8 }
 });
-/**
- * Open a mailbox environment and return the ready-to-use databaser.
- *
- * Compatibility rule:
- * - explicit mailbox opens stay strict
- * - missing additive sidecars are tolerated only by higher-level habery open
- *   flows that are inspecting compat stores readonly
- */
-export function* createMailboxer(options = {}) {
-    const mailboxer = new Mailboxer(options);
-    const opened = yield* mailboxer.reopen(options);
-    if (!opened) {
-        throw new DatabaseNotOpenError("Failed to open Mailboxer");
-    }
-    return mailboxer;
-}

package/esm/keri/npm/src/db/noting.js

@@ -23,8 +23,7 @@ var _Notice_raw, _Notice_pad;
  * - higher-level notification policy lives in `app/notifying.ts`
  */
 import { Cigar, MtrDex, Salter } from "cesr-ts";
-import { DatabaseNotOpenError } from "../core/errors.js";
-import { LMDBer } from "./core/lmdber.js";
+import { StoreOwner } from "./core/store-owner.js";
 import { CesrSuber, Suber } from "./subing.js";
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -128,20 +127,9 @@ class NoticeSuber extends Suber {
  * - `.nidx` stores `rid -> dt`
  * - `.ncigs` stores detached `Cigar`s for integrity verification
  */
-export class Noter extends LMDBer {
-    /** Select `.tufa/not` by default while preserving `.keri/not` compat mode. */
-    constructor(options = {}) {
-        const compat = options.compat ?? false;
-        super(options, {
-            tailDirPath: Noter.TailDirPath,
-            cleanTailDirPath: "keri/clean/not",
-            altTailDirPath: compat
-                ? Noter.CompatAltTailDirPath
-                : Noter.AltTailDirPath,
-            altCleanTailDirPath: compat ? ".keri/clean/not" : ".tufa/clean/not",
-            tempPrefix: Noter.TempPrefix,
-            maxNamedDBs: Noter.MaxNamedDBs,
-        });
+export class Noter extends StoreOwner {
+    constructor() {
+        super(...arguments);
         Object.defineProperty(this, "notes", {
             enumerable: true,
             configurable: true,
@@ -163,16 +151,16 @@ export class Noter extends LMDBer {
     }
     /** Open all notice, reverse-index, and detached-signature families. */
     *reopen(options = {}) {
-        const opened = yield* super.reopen(options);
+        const opened = yield* this.store.reopen(options);
         if (!opened) {
             return false;
         }
-        this.notes = new NoticeSuber(this, {
+        this.notes = new NoticeSuber(this.store, {
             subkey: "nots.",
             sep: "/",
         });
-        this.nidx = new Suber(this, { subkey: "nidx." });
-        this.ncigs = new CesrSuber(this, {
+        this.nidx = new Suber(this.store, { subkey: "nidx." });
+        this.ncigs = new CesrSuber(this.store, {
             subkey: "ncigs.",
             ctor: Cigar,
         });
@@ -249,42 +237,10 @@ export class Noter extends LMDBer {
         return pairs;
     }
 }
-Object.defineProperty(Noter, "TailDirPath", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: "keri/not"
-});
-Object.defineProperty(Noter, "AltTailDirPath", {
+/** Placement of this store kind. */
+Object.defineProperty(Noter, "Family", {
     enumerable: true,
     configurable: true,
     writable: true,
-    value: ".tufa/not"
+    value: { tail: "not", maxTables: 8 }
 });
-Object.defineProperty(Noter, "CompatAltTailDirPath", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: ".keri/not"
-});
-Object.defineProperty(Noter, "TempPrefix", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: "keri_not_"
-});
-Object.defineProperty(Noter, "MaxNamedDBs", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: 8
-});
-/** Open a notification sidecar and return the ready-to-use databaser. */
-export function* createNoter(options = {}) {
-    const noter = new Noter(options);
-    const opened = yield* noter.reopen(options);
-    if (!opened) {
-        throw new DatabaseNotOpenError("Failed to open Noter");
-    }
-    return noter;
-}