keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/core/{kram-policy.js → mailbox/kram-policy.js}

@@ -1,6 +1,6 @@
 /** KRAM cache selection and safe, receiver-clocked configuration transitions. */
 import { intToB64 } from "cesr-ts";
-import { CacheTypeRecord } from "./records.js";
+import { CacheTypeRecord } from "../records.js";
 /** Only this key owns the policy transition metadata in the existing settings table. */
 const policyKey = "kram-policy";
 /** Validate caller configuration before any durable policy mutation. */
@@ -79,6 +79,18 @@ function policyState(stored, db) {
         throw new Error("Corrupt KRAM policy metadata", { cause });
     }
 }
+/** OOBI endpoint replies rely on BADA acceptance rather than KRAM replay protection (KERIpy `OobiDenials`). */
+const OOBI_EXEMPTIONS = [[[2, 0], "rpy", "/end/role"], [[2, 0], "rpy", "/loc/scheme"]];
+/**
+ * Store-and-forward routes whose copy is correct whenever it arrives, so a late
+ * mailbox fetch must not fall outside a KRAM window (KERIpy
+ * `StoreForwardDenials`). Their own acceptance model replaces replay protection:
+ * the exchange store is keyed by SAID, the handler ignores a stored SAID that is
+ * escrowed or already retained, every copy is fully re-authorized against
+ * current KEL/TEL state and its root reproduced before automatic retention, and
+ * a retained root is immutable.
+ */
+const STORE_FORWARD_EXEMPTIONS = [[[2, 0], "exn", "/registry/root"]];
 /**
  * Own finite cache configuration and exemption policy, reusing Baser.ctyp.
  * Persist staged acceptance expansions so restart cannot reopen an old window.
@@ -127,9 +139,7 @@ export class KramPolicy {
         this.enabled = config.enabled ?? false;
         const denials = [
             ...(config.denials ?? []),
-            ...(this.enabled
-                ? [[[2, 0], "rpy", "/end/role"], [[2, 0], "rpy", "/loc/scheme"]]
-                : []),
+            ...(this.enabled ? [...OOBI_EXEMPTIONS, ...STORE_FORWARD_EXEMPTIONS] : []),
         ];
         this.exemptions = denials.map(([version, type, route]) => {
             if (version.length !== 2 || version.some((v) => !Number.isSafeInteger(v) || v < 0)

package/esm/keri/npm/src/core/{kram-pruning.js → mailbox/kram-pruning.js}

@@ -1,9 +1,9 @@
 /** Internal finite cache maintenance; each batch releases read cursors before writes. */
 import { b } from "cesr-ts";
-import { removeKramFactors } from "../db/kram-factors.js";
-import { timestampMicros } from "../time/mod.js";
+import { removeKramFactors } from "../../db/mailbox/kram-factors.js";
+import { timestampMicros } from "../../time/mod.js";
+import { TxnMsgCacheRecord } from "../records.js";
 import { kramCacheValues } from "./kram-time.js";
-import { TxnMsgCacheRecord } from "./records.js";
 /** Prune stored windows, then prove orphan XIDs with restartable finite existence scans. */
 export class KramPruner {
     constructor(db, policy) {

package/esm/keri/npm/src/core/{kram-signatures.js → mailbox/kram-signatures.js}

@@ -1,6 +1,6 @@
 /** Internal KRAM sender-factor normalization and signature verification. */
 import { Diger, NumberPrimitive, Siger } from "cesr-ts";
-import { KeriDispatchEnvelope, TransIdxSigGroup } from "./dispatch.js";
+import { KeriDispatchEnvelope, TransIdxSigGroup } from "../dispatch.js";
 /** Clone factor arrays while borrowing primitive/frame owners and retaining foreign evidence. */
 export function normalizeKramSenderFactors(incoming) {
     const envelope = new KeriDispatchEnvelope({ ...incoming, attachmentGroups: [...incoming.attachmentGroups] });

package/esm/keri/npm/src/core/{kram-staging.js → mailbox/kram-staging.js}

@@ -1,12 +1,12 @@
 /** Internal atomic KRAM staging; the intake owner supplies queries and plain ready decisions. */
 import { Dater, Diger, NumberPrimitive, } from "cesr-ts";
-import { rehydrateKramFactors, removeKramFactors, storeKramFactors } from "../db/kram-factors.js";
-import { encodeDateTimeToDater } from "../time/mod.js";
-import { KeriDispatchEnvelope, TransIdxSigGroup } from "./dispatch.js";
+import { rehydrateKramFactors, removeKramFactors, storeKramFactors } from "../../db/mailbox/kram-factors.js";
+import { encodeDateTimeToDater } from "../../time/mod.js";
+import { KeriDispatchEnvelope, TransIdxSigGroup } from "../dispatch.js";
+import { TxnMsgCacheRecord } from "../records.js";
 import { authenticateKramSource } from "./kram-auth.js";
 import { normalizeKramSenderFactors, verifyKramSignatures } from "./kram-signatures.js";
-import { evaluateKramTime, inspectKramReplay } from "./kram-time.js";
-import { TxnMsgCacheRecord } from "./records.js";
+import { evaluateKramTime, inspectKramReplay, } from "./kram-time.js";
 /** Bind verified or foreign factors to one accepted establishment tuple. */
 function establishmentGroup(kever, sigers) {
     return new TransIdxSigGroup(kever.prefixer, NumberPrimitive.fromNum(BigInt(kever.lastEst.s)), new Diger({ qb64: kever.lastEst.d }), sigers);
@@ -139,7 +139,7 @@ export function stageKram(db, policy, incoming, receiverTime) {
         const envelope = rehydrateKramFactors(db, key, received);
         if (fresh.multi) {
             envelope.sigers.splice(0, envelope.sigers.length, ...[...fresh.pool].sort((a, b) => a.index - b.index));
-            if (incoming.serder.ilk === "exn") {
+            if (["qry", "rpy", "xip", "exn"].includes(incoming.serder.ilk ?? "")) {
                 envelope.tsgs.splice(0, envelope.tsgs.length, establishmentGroup(fresh.kever, fresh.pool), ...envelope.tsgs.filter((group) => group.pre !== incoming.serder.pre));
             }
         }

package/esm/keri/npm/src/core/{kram-time.js → mailbox/kram-time.js}

@@ -1,5 +1,5 @@
-import { timestampMicros } from "../time/mod.js";
-import { MsgCacheRecord, TxnMsgCacheRecord } from "./records.js";
+import { timestampMicros } from "../../time/mod.js";
+import { MsgCacheRecord, TxnMsgCacheRecord } from "../records.js";
 /** Validate durable cache values without turning corruption into remote refusal. */
 export function kramCacheValues(cache) {
     const { mdt, d, ml, pml, xl, pxl } = cache;
@@ -28,8 +28,9 @@ export function inspectKramReplay(db, body) {
     const partial = db.pmkm.get(key) !== null;
     if (cache) {
         const values = kramCacheValues(cache);
-        if (mdt <= timestampMicros(values.mdt) && !partial)
+        if (mdt <= timestampMicros(values.mdt) && !partial) {
             return { kind: "drop", reason: "replay" };
+        }
     }
     return { kind: cache ? "cached" : "new", body, key, cacheKey, xid, mdt, partial, cache };
 }

package/esm/keri/npm/src/core/{kraming.js → mailbox/kraming.js}

@@ -1,5 +1,5 @@
-import { makeNowIso8601, timestampMicros } from "../time/mod.js";
-import { Deck } from "./deck.js";
+import { makeNowIso8601, timestampMicros } from "../../time/mod.js";
+import { Deck } from "../deck.js";
 import { KramPolicy } from "./kram-policy.js";
 import { KramPruner } from "./kram-pruning.js";
 import { stageKram } from "./kram-staging.js";

package/esm/keri/npm/src/core/protocol-eventing.js

@@ -9,8 +9,8 @@
 import { DigDex, DIGEST_CODES, Ilks, Kinds, NonceDex, Noncer, parseMatter, PREFIX_CODES, SerderKERI, Tholder, Vrsn_1_0, Vrsn_2_0, } from "cesr-ts";
 import { makeNowIso8601 } from "../time/mod.js";
 import { ValidationError } from "./errors.js";
+import { deriveRotatedWitnessSet, hasUniqueWitnesses } from "./kel/witnesses.js";
 import { KeyStateRecord, StateEERecord } from "./records.js";
-import { deriveRotatedWitnessSet, hasUniqueWitnesses } from "./witnesses.js";
 const MAX_INTIVE_THRESHOLD = 0xffff;
 function resolveVersionOptions(options, fallback = Vrsn_1_0) {
     const pvrsn = options?.pvrsn ?? options?.version ?? fallback;

package/esm/keri/npm/src/core/protocol-serialization.js

@@ -1,29 +1,7 @@
-import { concatBytes, Counter, CounterGroup, Kinds, LabelDex, NON_TRANSFERABLE_CODES, OpaqueSpan, Seqner, Texter, Vrsn_1_0, } from "cesr-ts";
+import { concatBytes, Counter, CounterGroup, Kinds, LabelDex, NON_TRANSFERABLE_CODES, OpaqueSpan, Texter, Vrsn_1_0, } from "cesr-ts";
 import { dgKey } from "../db/core/keys.js";
-import { attachmentCounterPayloadQb64b, attachmentCounterQb64b, pathedMaterialCounterQb64b, resolveAttachmentGvrsn, } from "./attachment-countering.js";
+import { attachmentCounterPayloadQb64b, attachmentCounterQb64b, attachmentOrdinal, pathedMaterialCounterQb64b, resolveAttachmentGvrsn, } from "./attachment-countering.js";
 import { ValidationError } from "./errors.js";
-function hexToFixedBytes(hex, size) {
-    const normalized = hex.length % 2 === 0 ? hex : `0${hex}`;
-    if (!/^[0-9a-f]+$/i.test(normalized)) {
-        throw new ValidationError(`Invalid hex ordinal ${hex}`);
-    }
-    if (normalized.length > size * 2) {
-        throw new ValidationError(`Hex ordinal ${hex} exceeds ${size} bytes.`);
-    }
-    const raw = new Uint8Array(size);
-    const padded = normalized.padStart(size * 2, "0");
-    for (let i = 0; i < size; i++) {
-        raw[i] = Number.parseInt(padded.slice(i * 2, (i * 2) + 2), 16);
-    }
-    return raw;
-}
-function encodeSealSeqnerQb64b(seq) {
-    if (seq instanceof Seqner) {
-        return seq.qb64b;
-    }
-    const snh = typeof seq === "string" ? seq : seq.numh;
-    return new Seqner({ code: "0A", raw: hexToFixedBytes(snh, 16) }).qb64b;
-}
 function concatMessageWithAttachmentGroup(serder, attachments, pipelined, gvrsn, nested, genusify) {
     const atc = attachments.length === 0 ? new Uint8Array() : concatBytes(...attachments);
     const prefix = genusify ? Counter.makeGVC(gvrsn) : new Uint8Array();
@@ -84,7 +62,7 @@ export function messagize(serderOrCreder, argsOrProof = {}, proofOptions = {}) {
         if (seal && "s" in seal && "d" in seal) {
             const transPayload = [
                 seal.i.qb64b,
-                encodeSealSeqnerQb64b(seal.s),
+                attachmentOrdinal(seal.s, gvrsn).qb64b,
                 seal.d.qb64b,
                 ...sigerGroup,
             ];
@@ -102,13 +80,12 @@ export function messagize(serderOrCreder, argsOrProof = {}, proofOptions = {}) {
         }
     }
     if (tsgs.length > 0) {
-        // Frozen 714 emits one aggregate group in supplied order; v2 preserves qualified ordinals.
+        // Frozen 714 emits one aggregate group in supplied order with genus-canonical ordinals.
         const payload = tsgs.flatMap((group) => {
             const signatures = group.sigers.map((siger) => siger.qb64b);
-            const ordinal = gvrsn.major >= 2 ? group.seqner.qb64b : encodeSealSeqnerQb64b(group.seqner);
             return [
                 group.prefixer.qb64b,
-                ordinal,
+                attachmentOrdinal(group.seqner, gvrsn).qb64b,
                 group.diger.qb64b,
                 attachmentCounterPayloadQb64b("ControllerIdxSigs", group.sigers.length, signatures, gvrsn),
                 ...signatures,
@@ -147,7 +124,7 @@ export function buildProof(prefixer, seqner, diger, sigers, gvrsn = Vrsn_1_0) {
     ];
     const transPayload = [
         prefixer.qb64b,
-        seqner.qb64b,
+        attachmentOrdinal(seqner, gvrsn).qb64b,
         diger.qb64b,
         ...sigerGroup,
     ];
@@ -176,10 +153,8 @@ export function messageAttachmentGroups({ tsgs = [], cigars = [], sourceSeals =
     for (const tsg of tsgs) {
         const sigers = tsg.sigers.map((siger) => siger.qb64b);
         const inner = attachmentCounterPayloadQb64b("ControllerIdxSigs", tsg.sigers.length, sigers, gvrsn);
-        // Frozen KERIpy v2 preserves the supplied qualified Number; only v1 widens it to Seqner.
-        const ordinal = gvrsn.major >= 2 || tsg.seqner instanceof Seqner
-            ? tsg.seqner
-            : new Seqner({ code: "0A", raw: hexToFixedBytes(tsg.snh, 16) });
+        // KERIpy writes the compact v2 Number or the fixed v1 Seqner, whichever ordinal it holds.
+        const ordinal = attachmentOrdinal(tsg.seqner, gvrsn);
         const payload = [tsg.prefixer.qb64b, ordinal.qb64b, tsg.diger.qb64b, inner, ...sigers];
         const header = attachmentCounterPayloadQb64b("TransIdxSigGroups", 1, payload, gvrsn);
         groups.push(new CounterGroup(new Counter({ qb64b: header, version: gvrsn }), concatBytes(header, ...payload), [[
@@ -198,7 +173,7 @@ export function messageAttachmentGroups({ tsgs = [], cigars = [], sourceSeals =
     if (sourceSeals.length) {
         const triples = sourceSeals.map((seal) => [
             seal.i,
-            gvrsn.major >= 2 ? seal.s : new Seqner({ code: "0A", raw: hexToFixedBytes(seal.s.numh, 16) }),
+            attachmentOrdinal(seal.s, gvrsn),
             seal.d,
         ]);
         const payload = triples.flatMap((triple) => triple.map((part) => part.qb64b));

package/esm/keri/npm/src/core/routing.js

@@ -1,9 +1,9 @@
-import { Dater, Diger, Prefixer, Siger } from "cesr-ts";
+import { Dater, Diger, NumberPrimitive, Prefixer, Siger } from "cesr-ts";
 import { encodeDateTimeToDater, timestampMicros } from "../time/mod.js";
 import { Deck } from "./deck.js";
 import { TransIdxSigGroup } from "./dispatch.js";
 import { ValidationError } from "./errors.js";
-import { acceptEscrow, dropEscrow, keepEscrow, logEscrowDecision, } from "./kever-decisions.js";
+import { acceptEscrow, dropEscrow, keepEscrow, logEscrowDecision, } from "./kel/kever-decisions.js";
 import { EndpointRecord, LocationRecord } from "./records.js";
 import { isRole } from "./roles.js";
 /** Builder for one accepted live reply decision. */
@@ -80,8 +80,8 @@ function sameOrNewerReply(nextDater, oldDater) {
  * Reconstruction steps:
  * - walk the stored signature rows under one message SAID
  * - regroup rows by `(pre, snh, dig)` back into transferable signature groups
- * - drop incomplete groups when the signer establishment event can no longer be
- *   resolved
+ * - reconstruct ordinals directly from stored keys, even while signer KEL
+ *   evidence is missing; ordinary reply verification owns that dependency check
  *
  * Ordering rule:
  * - groups are returned newest-first by establishment sequence number so reply
@@ -96,11 +96,7 @@ export function fetchStoredTsgs(db, said) {
         if (!prefix || !snh || !dig) {
             continue;
         }
-        const estEvent = db.getEvtSerder(prefix, dig);
-        const seqner = estEvent?.sner;
-        if (!seqner) {
-            continue;
-        }
+        const seqner = NumberPrimitive.fromNum(BigInt(`0x${snh}`));
         const prefixer = new Prefixer({ qb64: prefix });
         const diger = new Diger({ qb64: dig });
         const key = `${prefix}.${snh}.${dig}`;
@@ -222,6 +218,9 @@ export class Router {
      *
      * It does not do BADA or signature acceptance itself; those belong to
      * `Revery` and the route handler.
+     *
+     * @throws ValidationError for a missing or unregistered incoming route.
+     * @throws TypeError for an invalid configured handler or its return contract.
      */
     dispatch(args) {
         const route = args.serder.route;
@@ -238,12 +237,12 @@ export class Router {
                 : Router.defaultResourceFunc;
             const fn = Reflect.get(candidate.resource, funcName);
             if (typeof fn !== "function") {
-                throw new ValidationError(`Resource for route ${route} does not implement ${funcName}.`);
+                throw new TypeError(`Resource for route ${route} does not implement ${funcName}.`);
             }
             const params = match.groups ?? {};
             for (const field of candidate.fields) {
                 if (!(field in params)) {
-                    throw new ValidationError(`parameter ${field} not found in route ${route}`);
+                    throw new TypeError(`parameter ${field} not found in route ${route}`);
                 }
             }
             const decision = fn.call(candidate.resource, {
@@ -252,7 +251,7 @@ export class Router {
                 ...params,
             });
             if (!isReplyDecision(decision)) {
-                throw new ValidationError(`Reply route ${route} did not return a valid reply decision.`);
+                throw new TypeError(`Reply route ${route} did not return a valid reply decision.`);
             }
             return decision;
         }
@@ -432,7 +431,9 @@ export class Revery {
         const oldTsgs = args.osaider
             ? fetchStoredTsgs(this.db, args.osaider.qb64)
             : [];
-        const oldLead = oldTsgs[0];
+        // Reconstruction retains missing-key groups for retry. Only a group whose
+        // claimed ordinal matches its establishment event can lead prior BADA proof.
+        const oldLead = oldTsgs.find(tsg => this.db.getEvtSerder(tsg.pre, tsg.said)?.sner?.num === tsg.sn);
         for (const tsg of args.tsgs ?? []) {
             if (tsg.pre !== args.aid) {
                 continue;
@@ -565,8 +566,30 @@ export class Revery {
                 encodeOrdinalHex(args.seqner),
                 args.diger.qb64,
             ], args.sigers);
+            this.trimStaleReplyGroups(said, args.seqner, args.diger.qb64);
         }
     }
+    /**
+     * Drop signature groups from establishment events older than the accepted group.
+     *
+     * KERIpy `Revery.acceptReply` trims these after `updateReply` so the stored
+     * reply keeps only signatures from the current authoritative key state.
+     */
+    trimStaleReplyGroups(said, seqner, digest) {
+        const current = BigInt(`0x${encodeOrdinalHex(seqner)}`);
+        const stale = new Map();
+        for (const [keys] of this.db.ssgs.getTopItemIter([said], { topive: true })) {
+            const [, prefix, snh, dig] = keys;
+            if (!prefix || !snh || !dig)
+                continue;
+            const sn = BigInt(`0x${snh}`);
+            if (sn < current || (sn === current && dig !== digest)) {
+                stale.set(`${prefix}.${snh}.${dig}`, [said, prefix, snh, dig]);
+            }
+        }
+        for (const keys of stale.values())
+            this.db.ssgs.rem(keys);
+    }
     /**
      * Remove all persisted artifacts for one previously accepted reply SAID.
      *
@@ -631,15 +654,17 @@ export class Revery {
                 continue;
             }
             const decision = this.reprocessEscrowedReply(diger);
-            logEscrowDecision("Revery RPE", decision);
             switch (decision.kind) {
                 case "accept":
                     this.db.rpes.rem([route], diger);
                     break;
-                case "drop":
-                    this.db.rpes.rem([route], diger);
+                case "drop": {
+                    const removed = this.db.rpes.rem([route], diger);
                     this.removeReply(diger);
+                    if (removed)
+                        logEscrowDecision(`Revery RPE said=${diger.qb64} route=${route}`, decision);
                     break;
+                }
                 case "keep":
                     break;
             }
@@ -663,6 +688,12 @@ export class Revery {
      * - reject stale or malformed rows
      * - replay through `processReply()` exactly as if the reply re-arrived
      * - map recoverable live reply `unverified` decisions into `keep`
+     * - retain unexpected failures and their escrow evidence for the caller
+     *
+     * @param diger SAID identifying the stored reply and detached proof material.
+     * @returns The ordinary keep/drop/accept result; this method does not remove
+     *   the current escrow membership.
+     * @throws The original unexpected handler or infrastructure failure.
      */
     reprocessEscrowedReply(diger) {
         const dater = this.db.sdts.get([diger.qb64]);
@@ -682,7 +713,11 @@ export class Revery {
             return acceptEscrow();
         }
         catch (error) {
-            return dropEscrow("processingError", `${error instanceof Error ? error.message : String(error)} (said=${diger.qb64}, route=${serder.route})`);
+            // Remote validation may eject this reply; storage and handler defects must
+            // escape unchanged so the owning loop does not discard recoverable evidence.
+            if (!(error instanceof ValidationError))
+                throw error;
+            return dropEscrow("processingError", `${error.message} (said=${diger.qb64}, route=${serder.route})`, error);
         }
     }
 }

package/esm/keri/npm/src/db/baser-defaults.js

@@ -0,0 +1,11 @@
+/** Select Baser's persistent, alternate-home and temporary path conventions. */
+export function baserDefaults(compat = false) {
+    return {
+        tailDirPath: "keri/db",
+        cleanTailDirPath: "keri/clean/db",
+        altTailDirPath: compat ? ".keri/db" : ".tufa/db",
+        altCleanTailDirPath: compat ? ".keri/clean/db" : ".tufa/clean/db",
+        tempPrefix: "keri_db_",
+        maxNamedDBs: 128,
+    };
+}