keri-ts 0.10.1 → 0.10.2

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

@@ -0,0 +1,491 @@
+/**
+ * Verifiable data registry database owner.
+ *
+ * KERIpy correspondence:
+ * - mirrors `keri.vdr.eventing.Reger`
+ *
+ * Boundary:
+ * - this module owns durable VDR/TEL/credential storage and replay helpers
+ * - TEL state machines, registry orchestration, credential issuance, and
+ *   verifier policy live in later VDR runtime modules
+ */
+import { Cigar, concatBytes, Dater, Diger, NumberPrimitive, NumDex, Prefixer, Saider, Seqner, SerderACDC, Siger, t, Verfer, Vrsn_1_0, } from "cesr-ts";
+import { attachmentCounterPayloadQb64b, attachmentCounterQb64b } from "../core/attachment-countering.js";
+import { DatabaseNotOpenError, DatabaseOperationError, ValidationError } from "../core/errors.js";
+import { RegistryRecord, RegStateRecord } from "../core/records.js";
+import { dgKey } from "./core/keys.js";
+import { LMDBer } from "./core/lmdber.js";
+import { Broker } from "./escrowing.js";
+import { Komer } from "./koming.js";
+import { BytesSuber, CatCesrIoSetSuber, CatCesrSuber, CesrDupSuber, CesrIoSetSuber, CesrOnSuber, CesrSuber, IoDupSuber, OnIoDupSuber, SerderSuber, } from "./subing.js";
+function keyText(value) {
+    return typeof value === "string" ? value : t(value);
+}
+function digestText(value) {
+    if (value instanceof Diger || value instanceof Saider) {
+        return value.qb64;
+    }
+    return keyText(value);
+}
+function fixedOrdinalRaw(num, size = 16) {
+    const raw = new Uint8Array(size);
+    let value = num;
+    for (let i = raw.length - 1; i >= 0; i--) {
+        raw[i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    return raw;
+}
+function seqnerFromNumber(number) {
+    return new Seqner({ code: NumDex.Huge, raw: fixedOrdinalRaw(number.num) });
+}
+function saiderFromDigest(diger) {
+    return new Saider({ qb64: diger.qb64 });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * VDR/TEL credential database owner.
+ *
+ * Bound stores are literal KERIpy `Reger` subkeys. Keeping this class thin
+ * lets higher VDR processors share one storage contract with KERIpy fixtures.
+ */
+export class Reger extends LMDBer {
+    constructor(options = {}) {
+        const compat = options.compat ?? false;
+        super(options, {
+            tailDirPath: Reger.TailDirPath,
+            cleanTailDirPath: "keri/clean/reg",
+            altTailDirPath: compat ? Reger.CompatAltTailDirPath : Reger.AltTailDirPath,
+            altCleanTailDirPath: compat ? ".keri/clean/reg" : ".tufa/clean/reg",
+            tempPrefix: Reger.TempPrefix,
+            maxNamedDBs: Reger.MaxNamedDBs,
+        });
+        Object.defineProperty(this, "registries", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "tevers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "tvts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Serialized TEL events keyed by `(pre, said)`.
+        Object.defineProperty(this, "tels", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // TEL sequence ordinals mapped to event digests.
+        Object.defineProperty(this, "ancs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // TEL event source seal couples.
+        Object.defineProperty(this, "baks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Backer AIDs at one TEL management state.
+        Object.defineProperty(this, "tibs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Indexed backer receipt signatures.
+        Object.defineProperty(this, "oots", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Out-of-order TEL event escrows.
+        Object.defineProperty(this, "twes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Partially witnessed TEL event escrows.
+        Object.defineProperty(this, "taes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Anchorless TEL event escrows.
+        Object.defineProperty(this, "tets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // TEL event first-seen datetimes.
+        Object.defineProperty(this, "states", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Latest registry state records.
+        Object.defineProperty(this, "creds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Stored credentials by SAID.
+        Object.defineProperty(this, "cancs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Credential anchor triples.
+        Object.defineProperty(this, "spsgs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // SAD path indexed signatures.
+        Object.defineProperty(this, "spcgs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // SAD path non-indexed signatures.
+        Object.defineProperty(this, "saved", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Fully processed credential markers.
+        Object.defineProperty(this, "issus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Credential SAIDs indexed by issuer.
+        Object.defineProperty(this, "subjs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Credential SAIDs indexed by subject.
+        Object.defineProperty(this, "schms", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Credential SAIDs indexed by schema.
+        Object.defineProperty(this, "mre", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Missing registry escrow timestamps.
+        Object.defineProperty(this, "mce", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Missing chain escrow timestamps.
+        Object.defineProperty(this, "mse", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Missing schema escrow timestamps.
+        Object.defineProperty(this, "txnsb", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Transaction-state notice broker.
+        Object.defineProperty(this, "regs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Registry metadata keyed by name.
+        Object.defineProperty(this, "tpwe", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // TEL partial witness escrow.
+        Object.defineProperty(this, "tmse", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // TEL multisig anchor escrow.
+        Object.defineProperty(this, "tede", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // TEL dissemination escrow.
+        Object.defineProperty(this, "ctel", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Completed TEL event marker.
+        Object.defineProperty(this, "cmse", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Credential missing-signature escrow.
+        Object.defineProperty(this, "ccrd", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Completed credentials.
+    }
+    /** Open the root LMDB environment and bind the KERIpy `Reger` subdb surface. */
+    *reopen(options = {}) {
+        const opened = yield* super.reopen(options);
+        if (!opened) {
+            return false;
+        }
+        try {
+            this.tvts = new BytesSuber(this, { subkey: "tvts." });
+            this.tels = new CesrOnSuber(this, {
+                subkey: "tels.",
+                ctor: Diger,
+            });
+            this.ancs = new CatCesrSuber(this, {
+                subkey: "ancs.",
+                ctor: [NumberPrimitive, Diger],
+            });
+            this.baks = new IoDupSuber(this, { subkey: "baks." });
+            this.tibs = new CesrDupSuber(this, {
+                subkey: "tibs.",
+                ctor: Siger,
+            });
+            this.oots = new OnIoDupSuber(this, { subkey: "oots" });
+            this.twes = new OnIoDupSuber(this, { subkey: "twes" });
+            this.taes = new OnIoDupSuber(this, { subkey: "taes" });
+            this.tets = new CesrSuber(this, {
+                subkey: "tets.",
+                ctor: Dater,
+            });
+            this.states = new Komer(this, {
+                subkey: "stts.",
+                recordClass: RegStateRecord,
+            });
+            this.creds = new SerderSuber(this, {
+                subkey: "creds.",
+                ctor: SerderACDC,
+            });
+            this.cancs = new CatCesrSuber(this, {
+                subkey: "cancs.",
+                ctor: [Prefixer, NumberPrimitive, Diger],
+            });
+            this.spsgs = new CesrIoSetSuber(this, {
+                subkey: "ssgs.",
+                ctor: Siger,
+            });
+            this.spcgs = new CatCesrIoSetSuber(this, {
+                subkey: "scgs.",
+                ctor: [Verfer, Cigar],
+            });
+            this.saved = new CesrSuber(this, {
+                subkey: "saved.",
+                ctor: Saider,
+            });
+            this.issus = new CesrDupSuber(this, {
+                subkey: "issus.",
+                ctor: Saider,
+            });
+            this.subjs = new CesrDupSuber(this, {
+                subkey: "subjs.",
+                ctor: Saider,
+            });
+            this.schms = new CesrDupSuber(this, {
+                subkey: "schms.",
+                ctor: Saider,
+            });
+            this.mre = new CesrSuber(this, { subkey: "mre.", ctor: Dater });
+            this.mce = new CesrSuber(this, { subkey: "mce.", ctor: Dater });
+            this.mse = new CesrSuber(this, { subkey: "mse.", ctor: Dater });
+            this.txnsb = new Broker(this, "txn.");
+            this.regs = new Komer(this, {
+                subkey: "regs.",
+                recordClass: RegistryRecord,
+            });
+            this.tpwe = new CatCesrIoSetSuber(this, {
+                subkey: "tpwe.",
+                ctor: [Prefixer, NumberPrimitive, Diger],
+            });
+            this.tmse = new CatCesrIoSetSuber(this, {
+                subkey: "tmse.",
+                ctor: [Prefixer, NumberPrimitive, Diger],
+            });
+            this.tede = new CatCesrIoSetSuber(this, {
+                subkey: "tede.",
+                ctor: [Prefixer, NumberPrimitive, Saider],
+            });
+            this.ctel = new CesrSuber(this, {
+                subkey: "ctel.",
+                ctor: Saider,
+            });
+            this.cmse = new SerderSuber(this, {
+                subkey: "cmse.",
+                ctor: SerderACDC,
+            });
+            this.ccrd = new SerderSuber(this, {
+                subkey: "ccrd.",
+                ctor: SerderACDC,
+            });
+            return this.opened;
+        }
+        catch (error) {
+            throw new DatabaseOperationError("Failed to open Reger sub-databases", { cause: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /** Persist one base credential and its anchoring event triple. */
+    logCred(creder, prefixer, number, diger) {
+        const key = creder.said;
+        if (!key) {
+            throw new ValidationError("Cannot log credential without SAID.");
+        }
+        this.cancs.pin([key], [prefixer, number, diger]);
+        return this.creds.put([key], creder);
+    }
+    /** Load one stored credential and the event triple that anchored it. */
+    cloneCred(said) {
+        const creder = this.creds.get([said]);
+        if (creder === null) {
+            throw new ValidationError(`no credential found with said ${said}`);
+        }
+        const anchor = this.cancs.get([said]);
+        if (anchor === null) {
+            throw new ValidationError(`no credential anchor found with said ${said}`);
+        }
+        const [prefixer, number, diger] = anchor;
+        return [creder, prefixer, number, diger];
+    }
+    /** Iterate TEL event messages for `pre` from ordinal `fn`, with attachments. */
+    *clonePreIter(pre, fn = 0) {
+        for (const [, , diger] of this.tels.getAllItemIter(pre, fn)) {
+            yield this.cloneTvt(pre, diger);
+        }
+    }
+    /** Clone one TEL event message at sequence number `sn`, with attachments. */
+    cloneTvtAt(pre, sn = 0) {
+        const diger = this.tels.getOn(pre, sn);
+        if (diger === null) {
+            throw new ValidationError(`Missing event digest for pre=${keyText(pre)} sn=${sn}.`);
+        }
+        return this.cloneTvt(pre, diger);
+    }
+    /** Clone one TEL event message by digest, including KERIpy attachment groups. */
+    cloneTvt(pre, dig) {
+        const preText = keyText(pre);
+        const digText = digestText(dig);
+        const dgkey = dgKey(preText, digText);
+        const raw = this.tvts.get(dgkey);
+        if (raw === null) {
+            throw new ValidationError(`Missing event for dig=${digText}.`);
+        }
+        const attachments = [];
+        const tibs = this.tibs.get([preText, digText]);
+        if (tibs.length > 0) {
+            const tibPayload = tibs.map((tib) => tib.qb64b);
+            attachments.push(attachmentCounterPayloadQb64b("WitnessIdxSigs", tibs.length, tibPayload), ...tibPayload);
+        }
+        const couple = this.ancs.get(dgkey);
+        if (couple !== null) {
+            const [number, diger] = couple;
+            const sealPayload = [
+                seqnerFromNumber(number).qb64b,
+                saiderFromDigest(diger).qb64b,
+            ];
+            attachments.push(attachmentCounterPayloadQb64b("SealSourceCouples", 1, sealPayload), ...sealPayload);
+        }
+        const atc = attachments.length === 0 ? new Uint8Array() : concatBytes(...attachments);
+        if (atc.length % 4 !== 0) {
+            throw new ValidationError(`Invalid attachments size=${atc.length}, nonintegral quadlets.`);
+        }
+        return concatBytes(raw, attachmentCounterQb64b("AttachmentGroup", atc.length / 4), atc);
+    }
+    /** Return recursive source credentials with `SealSourceTriples` attachments. */
+    sources(_db, creder, gvrsn = Vrsn_1_0) {
+        const chains = isRecord(creder.edge) ? creder.edge : {};
+        const saids = [];
+        for (const [key, source] of Object.entries(chains)) {
+            if (key === "d" || !isRecord(source) || typeof source.n !== "string") {
+                continue;
+            }
+            saids.push(source.n);
+        }
+        const sources = [];
+        for (const said of saids) {
+            const [sourceCreder, prefixer, number, diger] = this.cloneCred(said);
+            const sealPayload = [
+                prefixer.qb64b,
+                number.qb64b,
+                saiderFromDigest(diger).qb64b,
+            ];
+            const atc = concatBytes(attachmentCounterPayloadQb64b("SealSourceTriples", 1, sealPayload, gvrsn), ...sealPayload);
+            sources.push([sourceCreder, atc]);
+            sources.push(...this.sources(_db, sourceCreder, gvrsn));
+        }
+        return sources;
+    }
+}
+Object.defineProperty(Reger, "TailDirPath", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: "keri/reg"
+});
+Object.defineProperty(Reger, "AltTailDirPath", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: ".tufa/reg"
+});
+Object.defineProperty(Reger, "CompatAltTailDirPath", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: ".keri/reg"
+});
+Object.defineProperty(Reger, "TempPrefix", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: "keri_reg_"
+});
+Object.defineProperty(Reger, "MaxNamedDBs", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 96
+});
+/** Transfer a ready `Reger` to its caller, closing unreturned acquisitions on failure or cancellation. */
+export function* createReger(options = {}) {
+    const reger = new Reger(options);
+    let delivered = false;
+    try {
+        const opened = yield* reger.reopen(options);
+        if (!opened) {
+            throw new DatabaseNotOpenError("Failed to open Reger");
+        }
+        delivered = true;
+        return reger;
+    }
+    finally {
+        if (!delivered)
+            yield* reger.close();
+    }
+}