cesr-ts 0.4.0 → 0.6.0

package/esm/src/primitives/codex.js

@@ -1,16 +1,29 @@
 import { codexValues, invertCodex } from "../tables/codex-utils.js";
-import { IdrDex, IdxBthSigDex, IdxCrtSigDex, IdxSigDex, } from "../tables/indexer.codex.generated.js";
+import { IdrDex, IdxBthSigDex, IdxCrtSigDex, IdxSigDex } from "../tables/indexer.codex.generated.js";
 import { BexDex, CiXAllQB64Dex, CiXDex, CiXFixQB64Dex, CiXVarDex, CiXVarQB2Dex, CiXVarQB64Dex, CiXVarStrmDex, DecDex, DigDex, EscapeDex, LabelDex, MtrDex, NonceDex, NonTransDex, NumDex, PreDex, PreNonDigDex, TagDex, TexDex, } from "../tables/matter.codex.generated.js";
 import { TraitDex } from "../tables/trait.codex.generated.js";
 import { Protocols } from "../tables/versions.js";
 /**
  * Derived readability layer over the generated KERIpy-parity codex objects.
  *
- * Canonical names such as `MtrDex`, `PreDex`, `DigDex`, and `IdrDex` are the
- * primary source of truth. The sets exported here are convenience views for
- * primitive-family validation and TS ergonomics.
+ * Canonical names such as `MtrDex` and `IdrDex` are the primary source of
+ * truth for the shared Matter/Indexer code spaces. Semantic families such as
+ * `PreDex`, `DigDex`, `NonceDex`, and `IdxSigDex` are KERIpy-style subset
+ * views over those same base codices, not separate versioned registries.
+ *
+ * The sets exported here are convenience views for primitive-family validation
+ * and TS ergonomics. Counter codices are the separate genus/version-aware
+ * layer; Matter and Indexer family subsets are not.
  */
 export { BexDex, CiXAllQB64Dex, CiXDex, CiXFixQB64Dex, CiXVarDex, CiXVarQB2Dex, CiXVarQB64Dex, CiXVarStrmDex, DecDex, DigDex, EscapeDex, IdrDex, IdxBthSigDex, IdxCrtSigDex, IdxSigDex, LabelDex, MtrDex, NonceDex, NonTransDex, NumDex, PreDex, PreNonDigDex, TagDex, TexDex, TraitDex, };
+/**
+ * Derived matter/indexer family views used by semantic primitive validators.
+ *
+ * Maintainer rule:
+ * - generated codex objects such as `MtrDex`, `PreDex`, and `IdrDex` remain
+ *   the authority
+ * - these exported sets are readability helpers layered over that authority
+ */
 export const BEXTER_CODES = codexValues(BexDex);
 export const TEXTER_CODES = codexValues(TexDex);
 export const DECIMAL_CODES = codexValues(DecDex);
@@ -20,9 +33,18 @@ export const NUMBER_CODES = codexValues(NumDex);
 export const TAG_CODES = codexValues(TagDex);
 export const LABELER_CODES = codexValues(LabelDex);
 export const PREFIX_CODES = codexValues(PreDex);
-export const NON_TRANSFERABLE_PREFIX_CODES = codexValues(NonTransDex);
+export const NON_TRANSFERABLE_CODES = codexValues(NonTransDex);
 export const NON_DIGEST_PREFIX_CODES = codexValues(PreNonDigDex);
 export const ESCAPE_CODES = codexValues(EscapeDex);
+/**
+ * X25519 cipher-family helper sets keyed by plaintext hydration rules.
+ *
+ * KERIpy correspondence:
+ * - stream families preserve whole sniffable CESR streams
+ * - qb64 families preserve fully qualified text material
+ * - qb2 families preserve binary CESR encodings
+ * - fixed qb64 families name the common salt/seed payloads directly
+ */
 export const CIPHER_X25519_VARIABLE_STREAM_CODES = codexValues(CiXVarStrmDex);
 export const CIPHER_X25519_QB64_VARIABLE_CODES = codexValues(CiXVarQB64Dex);
 export const CIPHER_X25519_FIXED_QB64_CODES = codexValues(CiXFixQB64Dex);
@@ -45,6 +67,13 @@ export const THOLDER_CODES = new Set([
     ...THOLDER_NUMERIC_CODES,
     ...THOLDER_WEIGHTED_CODES,
 ]);
+/**
+ * Executable primitive suite families.
+ *
+ * These are the small semantic validation sets consumed by `Signer`,
+ * `Salter`, `Encrypter`, `Decrypter`, and detached-signature primitives, not
+ * alternative registries separate from the generated KERIpy parity codices.
+ */
 export const SIGNER_CODES = new Set([
     MtrDex.Ed25519_Seed,
     MtrDex.ECDSA_256k1_Seed,
@@ -63,8 +92,12 @@ export const TRAIT_TAGS = new Set([
     ...codexValues(TraitDex),
 ]);
 export const VERSER_CODES = new Set([MtrDex.Tag7, MtrDex.Tag10]);
-export const VERSER_PROTOCOLS = new Set(Object.values(Protocols));
+export const VERSER_PROTOCOLS = new Set([
+    ...Object.values(Protocols),
+    "OCSR",
+]);
 const MATTER_CODEX_NAMES = invertCodex(MtrDex);
+/** Project one matter code back to its generated codex member name. */
 export function matterCodexName(code) {
     return MATTER_CODEX_NAMES.get(code);
 }

package/esm/src/primitives/compactor.js

@@ -1,10 +1,314 @@
-import { UnknownCodeError } from "../core/errors.js";
+import { DeserializeError, UnknownCodeError } from "../core/errors.js";
 import { COMPACTOR_CODES } from "../tables/counter-groups.js";
-import { parseMapperBody } from "./mapper.js";
+import { Mapper, parseMapperBody } from "./mapper.js";
+/**
+ * CESR-native compactable map primitive.
+ *
+ * Maintainer mental model:
+ * a `Compactor` is a `Mapper` plus the tree-walking utilities needed to turn
+ * nested saidive maps into their "most compact" branch form and then re-expand
+ * them into readable partial-disclosure variants. `leaves` records the saidive
+ * map nodes discovered during tracing; `partials` records staged re-expansions.
+ */
+export class Compactor extends Mapper {
+    /**
+     * Construct one compactable map primitive.
+     *
+     * If `compactify=true` and the input starts from semantic `mad`, the
+     * constructor eagerly runs the compact + expand lifecycle so callers
+     * immediately get both the compact current state and readable partials.
+     */
+    constructor(init = {}) {
+        super({
+            ...init,
+            saidive: init.saidive ?? true,
+            verify: init.verify ?? true,
+        });
+        /** Leaf-path index populated by `trace()`: dotted path -> saidified leaf mapper. */
+        Object.defineProperty(this, "leaves", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Partially re-expanded disclosure variants built by `expand()`. */
+        Object.defineProperty(this, "partials", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (!COMPACTOR_CODES.has(this.code)) {
+            throw new UnknownCodeError(`Expected map compactor group code, got ${this.code}`);
+        }
+        this.leaves = {};
+        this.partials = null;
+        if (init.mad && (init.compactify ?? false)) {
+            this.compact();
+            this.expand();
+        }
+    }
+    /** Primary SAID of the current map state, if its configured saidive label is present. */
+    get said() {
+        const label = Object.keys(this.saids)[0];
+        const value = this._mad[label];
+        return typeof value === "string" ? value : null;
+    }
+    /**
+     * True when the current map is fully compacted.
+     *
+     * `true` means the root map itself is a leaf and its own saidive value is the
+     * compact representation. `false` means there are leaves but at least one
+     * branch is still expanded. `null` means the map tree has no saidive leaves.
+     */
+    get iscompact() {
+        const paths = Object.keys(this.leaves);
+        if (paths.length === 0) {
+            return null;
+        }
+        return this.said !== null && "" in this.leaves;
+    }
+    /** Return the nested tail value located at dotted `path`, or `null` when absent. */
+    getTail(path, mad = null) {
+        let tail = mad ?? this._mad;
+        const parts = path.split(".").slice(1);
+        for (const part of parts) {
+            if (!tail || typeof tail !== "object" || Array.isArray(tail)
+                || !(part in tail)) {
+                return null;
+            }
+            tail = tail[part];
+        }
+        return tail;
+    }
+    /**
+     * Return the enclosing map and tail label for dotted `path`.
+     *
+     * Example:
+     * path `.a.address` => returns the map stored at `.a` plus tail `"address"`.
+     * path `` (top level) => returns `[null, ""]`.
+     */
+    getMad(path, mad = null) {
+        let current = mad ?? this._mad;
+        const parts = path.split(".");
+        const tail = parts.at(-1) ?? null;
+        const parents = parts.slice(1, -1);
+        if (parts.length <= 1) {
+            return [null, tail];
+        }
+        for (const part of parents) {
+            const next = current[part];
+            if (!next || typeof next !== "object" || Array.isArray(next)) {
+                return [null, tail];
+            }
+            current = next;
+        }
+        if (tail !== null && tail !== "" && !(tail in current)) {
+            return [null, null];
+        }
+        return [current, tail];
+    }
+    /**
+     * Walk the nested map tree and index every saidive leaf by dotted path.
+     *
+     * When `saidify=true`, each leaf map is first rebuilt as a `Mapper` with
+     * `makify=true` so its leaf SAID is computed before the path is recorded.
+     */
+    trace(saidify = false) {
+        this.leaves = {};
+        const paths = this._trace(this._mad, [], "", saidify);
+        if (saidify && this.iscompact === false) {
+            // When nested leaves have just been saidified, the top-level map's own
+            // SAID must also be recomputed over that updated structure.
+            const top = Mapper.fromSad(this._mad, {
+                strict: this.strict,
+                saidive: true,
+                saids: this.saids,
+                kind: this.kind,
+                makify: true,
+                verify: false,
+            });
+            this._mad = top.mad;
+            this.raw = top.raw;
+            this.fields = top.fields;
+            this.code = top.code;
+            this.count = top.count;
+            this.fullSize = top.fullSize;
+            this.fullSizeB2 = top.fullSizeB2;
+            this.totalSize = top.totalSize;
+            this.totalSizeB2 = top.totalSizeB2;
+        }
+        return paths;
+    }
+    /** Apply the most-compact branch reduction recursively until the root is compact or no leaves exist. */
+    compact() {
+        while (true) {
+            const paths = this.trace(true);
+            for (const path of paths) {
+                const leafer = this.leaves[path];
+                const [mad, tail] = this.getMad(path);
+                if (mad && tail) {
+                    // Replacing a nested leaf map with its SAID is the actual "compaction"
+                    // step. `trace(true)` did the saidification; this step does the branch
+                    // contraction.
+                    mad[tail] = leafer.said;
+                }
+            }
+            if (paths.length === 0 || this.iscompact) {
+                break;
+            }
+        }
+        const rebuilt = Mapper.fromSad(this._mad, {
+            strict: this.strict,
+            saidive: true,
+            saids: this.saids,
+            kind: this.kind,
+            verify: false,
+        });
+        this._mad = rebuilt.mad;
+        this.raw = rebuilt.raw;
+        this.fields = rebuilt.fields;
+        this.code = rebuilt.code;
+        this.count = rebuilt.count;
+        this.fullSize = rebuilt.fullSize;
+        this.fullSizeB2 = rebuilt.fullSizeB2;
+        this.totalSize = rebuilt.totalSize;
+        this.totalSizeB2 = rebuilt.totalSizeB2;
+    }
+    /**
+     * Build readable partial-disclosure variants by progressively re-expanding compact leaves.
+     *
+     * `greedy=true` mirrors KERIpy’s preferred order: expand deeper leaves first
+     * so each staged variant reveals as much structure as possible per step.
+     */
+    expand(greedy = true) {
+        this.partials = {};
+        let paths = Object.keys(this.leaves);
+        if (greedy) {
+            paths = [...paths].reverse();
+        }
+        const used = [];
+        if (paths.includes("")) {
+            const top = this.leaves[""];
+            const partial = new Compactor({
+                mad: top.mad,
+                verify: false,
+                saidive: false,
+                strict: this.strict,
+                kind: this.kind,
+            });
+            partial.trace(false);
+            this.partials[""] = partial;
+            used.push("");
+        }
+        const pmad = this.mad;
+        while (true) {
+            const unused = paths.filter((path) => !used.includes(path));
+            if (unused.length === 0) {
+                break;
+            }
+            let created = false;
+            for (const path of unused) {
+                const [mad, tail] = this.getMad(path, pmad);
+                if (!mad || !tail) {
+                    continue;
+                }
+                // Replacing one compact SAID with the full leaf map is the inverse
+                // operation of `compact()`. Repeating this step builds a staircase of
+                // disclosure variants from compact to expanded.
+                mad[tail] = this.leaves[path].mad;
+                used.push(path);
+                created = true;
+            }
+            if (created) {
+                const partial = new Compactor({
+                    mad: pmad,
+                    verify: false,
+                    saidive: false,
+                    strict: this.strict,
+                    kind: this.kind,
+                });
+                const index = partial.trace(false);
+                this.partials[index.join("|")] = partial;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    _trace(mad, paths, path, saidify) {
+        // A map is a leaf when it has one of the configured saidive labels at this
+        // level and no descendant map with its own saidive field. That is the key
+        // mental model for every compact/disclose operation in this class.
+        let isLeaf = Object.keys(this.saids).some((label) => label in mad);
+        for (const [label, value] of Object.entries(mad)) {
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                if (label in this.saids) {
+                    throw new DeserializeError(`Got nested map in said field label=${label}`);
+                }
+                if (this._hasSaid(value)) {
+                    isLeaf = false;
+                    this._trace(value, paths, `${path}.${label}`, saidify);
+                }
+            }
+        }
+        if (isLeaf) {
+            paths.push(path);
+            // Each leaf is normalized through plain `Mapper` so `Compactor` stays
+            // focused on tree traversal and branch replacement rather than duplicating
+            // base map serialization logic.
+            const leafer = Mapper.fromSad(mad, {
+                strict: this.strict,
+                saidive: true,
+                saids: this.saids,
+                kind: this.kind,
+                makify: true,
+                verify: false,
+            });
+            if (saidify) {
+                for (const label of Object.keys(this.saids)) {
+                    if (label in mad && leafer.mad[label] !== undefined) {
+                        mad[label] = leafer.mad[label];
+                    }
+                }
+            }
+            this.leaves[path] = leafer;
+        }
+        return paths;
+    }
+    _hasSaid(mad) {
+        // This recursive predicate is deliberately separate from `_trace()` because
+        // the leaf test is the hardest part of compactor reasoning; keeping it in
+        // one helper makes future parity changes less error-prone.
+        for (const [label, value] of Object.entries(mad)) {
+            if (label in this.saids) {
+                return true;
+            }
+            if (value && typeof value === "object" && !Array.isArray(value)
+                && this._hasSaid(value)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Parse one CESR-native map body/group and hydrate it as a `Compactor`.
+ *
+ * Example:
+ * a native section like `-GAB0J_dE...0J_x-GA...` becomes a `Compactor` whose
+ * `.mad` is the readable nested object and whose `.qb64` is the exact native
+ * map-group bytes used on the wire.
+ */
 export function parseCompactor(input, version, cold) {
     const mapper = parseMapperBody(input, version, cold);
     if (!COMPACTOR_CODES.has(mapper.code)) {
         throw new UnknownCodeError(`Expected map compactor group code, got ${mapper.code}`);
     }
-    return mapper;
+    return new Compactor({
+        ...(cold === "txt" ? { raw: mapper.raw } : { qb2: input }),
+        version,
+        kind: "CESR",
+        verify: false,
+    });
 }

package/esm/src/primitives/counter.js

@@ -1,6 +1,6 @@
-import { b, b64ToInt, codeB2ToB64, codeB64ToB2, intToB64, nabSextets, sceil, } from "../core/bytes.js";
+import { b, b64ToInt, codeB2ToB64, codeB64ToB2, intToB64, nabSextets, sceil } from "../core/bytes.js";
 import { DeserializeError, ShortageError, UnknownCodeError } from "../core/errors.js";
-import { resolveCounterCodeNameTable, resolveCounterSizeTable, } from "../tables/counter-version-registry.js";
+import { resolveCounterCodeNameTable, resolveCounterSizeTable } from "../tables/counter-version-registry.js";
 import { COUNTER_HARDS } from "../tables/counter.tables.generated.js";
 const COUNTER_BARDS = new Map([...COUNTER_HARDS.entries()].map(([code, hs]) => [
     String.fromCharCode(codeB64ToB2(code)[0])
@@ -18,6 +18,7 @@ function getTables(version) {
     const nameTable = resolveCounterCodeNameTable(version);
     return { sizeTable, nameTable };
 }
+/** Inhale one text-domain counter token using the version-selected counter tables. */
 function parseCounterFromTextData(input, version) {
     const txt = String.fromCharCode(...input);
     if (txt.length === 0) {
@@ -62,6 +63,7 @@ function parseCounterFromTextData(input, version) {
         version,
     };
 }
+/** Inhale one qb2 counter token into the canonical text-oriented counter shape. */
 function parseCounterFromBinaryData(input, version) {
     if (input.length < 2) {
         throw new ShortageError(2, input.length);
@@ -100,6 +102,7 @@ function parseCounterFromBinaryData(input, version) {
         version,
     };
 }
+/** Exhale a counter code/count pair into its fully qualified versioned token. */
 function encodeCounterFromFields(code, count, version) {
     const { sizeTable, nameTable } = getTables(version);
     const sizage = sizeTable.get(code);
@@ -123,6 +126,7 @@ function encodeCounterFromFields(code, count, version) {
         version,
     };
 }
+/** Normalize the supported constructor variants into one shared counter payload. */
 function parseCounterInit(init) {
     const version = init.version ?? { major: 2, minor: 0 };
     if (init.code !== undefined) {

package/esm/src/primitives/dater.js

@@ -14,8 +14,7 @@ function toIso8601(dts) {
  */
 export class Dater extends Matter {
     constructor(init) {
-        const matter = init instanceof Matter ? init : new Matter(init);
-        super(matter);
+        super(init);
         if (!DATER_CODES.has(this.code)) {
             throw new UnknownCodeError(`Expected dater DateTime code, got ${this.code}`);
         }

package/esm/src/primitives/decimer.js

@@ -29,23 +29,19 @@ function rawifyDns(dns) {
  */
 export class Decimer extends Matter {
     constructor(init) {
-        if (!(init instanceof Matter)
+        const matterInit = (!(init instanceof Matter)
             && !init.raw
             && !init.qb64
             && !init.qb64b
             && !init.qb2
-            && (init.dns !== undefined || init.decimal !== undefined)) {
-            const dns = init.dns ?? `${init.decimal}`;
-            super({
+            && (init.dns !== undefined || init.decimal !== undefined))
+            ? {
                 ...init,
-                raw: rawifyDns(dns),
+                raw: rawifyDns(init.dns ?? `${init.decimal}`),
                 code: init.code ?? "4H",
-            });
-        }
-        else {
-            const matter = init instanceof Matter ? init : new Matter(init);
-            super(matter);
-        }
+            }
+            : init;
+        super(matterInit);
         if (!DECIMAL_CODES.has(this.code)) {
             throw new UnknownCodeError(`Expected decimal code, got ${this.code}`);
         }

package/esm/src/primitives/decrypter.js

@@ -1,18 +1,134 @@
-import { UnknownCodeError } from "../core/errors.js";
-import { DECRYPTER_CODES } from "./codex.js";
+import { DeserializeError, UnknownCodeError } from "../core/errors.js";
+import { normalizeByteLike } from "./byte-like.js";
+import { Cipher } from "./cipher.js";
+import { CIPHER_X25519_ALL_QB64_CODES, CIPHER_X25519_FIXED_QB64_CODES, CIPHER_X25519_QB2_VARIABLE_CODES, CIPHER_X25519_VARIABLE_STREAM_CODES, DECRYPTER_CODES, MtrDex, } from "./codex.js";
 import { Matter } from "./matter.js";
+import { Salter } from "./salter.js";
+import { boxKeyPairFromEd25519Seed, boxPublicKeyFromPrivateKey, openSealedBox } from "./sealed-box.js";
+import { Signer } from "./signer.js";
+import { Streamer } from "./streamer.js";
+/** Normalize direct X25519 or derived-Ed25519 constructor forms into `Matter` input. */
+function normalizeMatterInit(init) {
+    if (init instanceof Matter) {
+        return init;
+    }
+    const normalized = {
+        code: init.code ?? MtrDex.X25519_Private,
+    };
+    if (init.raw) {
+        normalized.raw = normalizeByteLike(init.raw);
+        return normalized;
+    }
+    if (init.qb64b) {
+        normalized.qb64b = normalizeByteLike(init.qb64b);
+        return normalized;
+    }
+    if (init.qb64) {
+        normalized.qb64b = normalizeByteLike(init.qb64);
+        return normalized;
+    }
+    if (init.qb2) {
+        normalized.qb2 = normalizeByteLike(init.qb2);
+        return normalized;
+    }
+    if (!init.seed) {
+        return normalized;
+    }
+    const signer = new Signer({ qb64b: normalizeByteLike(init.seed) });
+    if (signer.code !== MtrDex.Ed25519_Seed) {
+        throw new DeserializeError(`Unsupported signing seed derivation code = ${signer.code}.`);
+    }
+    normalized.raw = boxKeyPairFromEd25519Seed(signer.raw).privateKey;
+    return normalized;
+}
+function hydratePlaintext(cipher, plain, ctor, transferable) {
+    if (CIPHER_X25519_ALL_QB64_CODES.has(cipher.code)) {
+        return new ctor({ qb64b: plain, transferable });
+    }
+    if (CIPHER_X25519_QB2_VARIABLE_CODES.has(cipher.code)) {
+        return new ctor({ qb2: plain });
+    }
+    if (CIPHER_X25519_VARIABLE_STREAM_CODES.has(cipher.code)) {
+        return new ctor({ stream: plain });
+    }
+    throw new UnknownCodeError(`Unsupported cipher code = ${cipher.code}.`);
+}
+/**
+ * Resolve the default plaintext constructor implied by one cipher family.
+ *
+ * KERIpy correspondence:
+ * - fixed salt/seed families default to `Salter` / `Signer`
+ * - whole-stream families default to `Streamer`
+ * - generic qb64/qb2 variable families still require the caller to say what
+ *   semantic primitive should be rehydrated from the plaintext bytes
+ */
+function defaultCtorForCipher(cipher) {
+    if (cipher.code === MtrDex.X25519_Cipher_Salt) {
+        return Salter;
+    }
+    if (cipher.code === MtrDex.X25519_Cipher_Seed) {
+        return Signer;
+    }
+    if (CIPHER_X25519_VARIABLE_STREAM_CODES.has(cipher.code)) {
+        return Streamer;
+    }
+    if (CIPHER_X25519_FIXED_QB64_CODES.has(cipher.code)
+        || CIPHER_X25519_QB2_VARIABLE_CODES.has(cipher.code)
+        || CIPHER_X25519_ALL_QB64_CODES.has(cipher.code)) {
+        throw new UnknownCodeError(`Unsupported cipher code = ${cipher.code} when ctor is missing.`);
+    }
+    throw new UnknownCodeError(`Unsupported cipher code = ${cipher.code}.`);
+}
 /**
  * Private-key decryption primitive for asymmetric envelope payloads.
  *
- * KERIpy substance: decrypter material is private X25519 key material used to
- * recover plaintext from cipher envelopes (often derived from signing seeds).
+ * KERIpy substance: `Decrypter` owns the private X25519 material used to
+ * recover CESR payloads from sealed-box ciphers, optionally deriving it from
+ * an Ed25519 signing seed.
  */
 export class Decrypter extends Matter {
-    constructor(init) {
-        const matter = init instanceof Matter ? init : new Matter(init);
-        super(matter);
+    /**
+     * Construct one X25519 private-key decrypter.
+     *
+     * Default code remains the KERIpy private-box family
+     * `MtrDex.X25519_Private`.
+     */
+    constructor(init = {}) {
+        super(normalizeMatterInit(init));
         if (!DECRYPTER_CODES.has(this.code)) {
             throw new UnknownCodeError(`Expected decrypter key code, got ${this.code}`);
         }
     }
+    /**
+     * Decrypt one cipher and rehydrate the plaintext with the requested
+     * constructor.
+     *
+     * Resolution rules:
+     * - `cipher` wins when supplied
+     * - otherwise `qb64` is parsed before `qb2`
+     * - omitted `ctor` is only inferred for the KERIpy families that already
+     *   name their semantic plaintext shape
+     *
+     * Output rules:
+     * - `bare=true` returns plaintext bytes directly
+     * - otherwise `transferable` is forwarded only to qb64-family primitive
+     *   constructors such as `Signer`, matching the KERIpy init seam
+     */
+    decrypt({ cipher, qb64, qb2, ctor, transferable = false, bare = false, } = {}) {
+        const hydrated = cipher
+            ?? (qb64
+                ? new Cipher({ qb64b: normalizeByteLike(qb64) })
+                : qb2
+                    ? new Cipher({ qb2: normalizeByteLike(qb2) })
+                    : null);
+        if (!hydrated) {
+            throw new DeserializeError("Need one of cipher, qb64, or qb2.");
+        }
+        const plain = openSealedBox(hydrated.raw, boxPublicKeyFromPrivateKey(this.raw), this.raw);
+        if (bare) {
+            return plain;
+        }
+        const effectiveCtor = (ctor ?? defaultCtorForCipher(hydrated));
+        return hydratePlaintext(hydrated, plain, effectiveCtor, transferable);
+    }
 }