cesr-ts 0.4.0 → 0.5.0

package/esm/src/primitives/aggor.js

@@ -1,8 +1,26 @@
-import { UnknownCodeError } from "../core/errors.js";
+import { b, codeB2ToB64 } from "../core/bytes.js";
+import { DeserializeError, SerializeError, UnknownCodeError } from "../core/errors.js";
+import { CtrDexV2 } from "../tables/counter-codex.js";
 import { AGGOR_CODES, AGGOR_LIST_CODES, AGGOR_MAP_CODES } from "../tables/counter-groups.js";
-import { parseCompactor } from "./compactor.js";
-import { parseCounter } from "./counter.js";
+import { MATTER_SIZES } from "../tables/matter.tables.generated.js";
+import { DigDex } from "./codex.js";
+import { Counter, parseCounter } from "./counter.js";
+import { Diger } from "./diger.js";
+import { Mapper, parseMapperBody } from "./mapper.js";
+import { parseMatter } from "./matter.js";
 import { parseStructor, Structor } from "./structor.js";
+/**
+ * `Aggor` is the aggregate-list sibling to `Compactor`.
+ *
+ * Where `Compactor` contracts nested map branches to SAIDs, `Aggor` contracts a
+ * list of aggregate elements down to one commitment in slot zero (`agid`) while
+ * still supporting later selective disclosure of map elements.
+ *
+ * Boundary rule:
+ * - `Aggor` owns selective disclosure for aggregate lists
+ * - `Compactor` owns hierarchical map disclosure
+ * - `disclosure.ts` owns fixed-field blind/bound/media disclosure
+ */
 /** True when counter code belongs to aggregate-list group families. */
 export function isAggorListCode(code) {
     return AGGOR_LIST_CODES.has(code);
@@ -16,20 +34,32 @@ export function isAggorCode(code) {
     return AGGOR_CODES.has(code);
 }
 /**
- * Aggregate list/map structor primitive.
+ * Aggregate list/map primitive.
  *
- * KERIpy substance: `Aggor` represents counted aggregate list/map payload
- * groups and exposes either tuple/list items or semantic map fields.
+ * KERIpy substance:
+ * - list-form `Aggor` owns aggregate-element-list (`ael`) semantics and `agid`
+ *   computation/disclosure
+ * - map-form `Aggor` is preserved here only as a compatibility bridge for
+ *   parser-group projections that still classify generic map groups as aggor
+ *   families in the TS codebase
+ *
+ * The important tradeoff is intentional:
+ * - the list lane is the real graduated-disclosure story here
+ * - the map lane mainly keeps parser projections lossless and readable
  */
 export class Aggor extends Structor {
+    /**
+     * Construct one aggregate primitive.
+     *
+     * Two semantic lanes exist:
+     * - list lane: real aggregate semantics (`ael`, `agid`, disclosure)
+     * - map lane: compatibility bridge for existing TS parser projections that
+     *   still bucket generic map groups into aggregate families
+     */
     constructor(init) {
-        const payload = init instanceof Structor
-            ? { structor: init }
-            : "structor" in init
-                ? init
-                : {
-                    structor: new Structor(init),
-                };
+        const payload = "structor" in init
+            ? init
+            : Aggor.materializeStructor(init);
         super(payload.structor);
         Object.defineProperty(this, "kind", {
             enumerable: true,
@@ -37,48 +67,362 @@ export class Aggor extends Structor {
             writable: true,
             value: void 0
         });
+        /** Map-style compatibility projection for parser-origin map groups. */
         Object.defineProperty(this, "mapFields", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "strict", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "saids", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Digest code used to compute the aggregate identifier (`agid`). */
+        Object.defineProperty(this, "digestCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "wireKind", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_ael", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         if (!isAggorCode(this.code)) {
             throw new UnknownCodeError(`Expected aggregate list/map group code, got ${this.code}`);
         }
         this.kind = isAggorMapCode(this.code) ? "map" : "list";
         this.mapFields = payload.mapFields;
+        this.strict = "structor" in init
+            ? true
+            : (init.strict ?? true);
+        this.saids = {
+            ...("structor" in init
+                ? {}
+                : (init.saids ?? { d: DigDex.Blake3_256 })),
+        };
+        this.digestCode = "structor" in init
+            ? DigDex.Blake3_256
+            : (init.code ?? DigDex.Blake3_256);
+        this.wireKind = "structor" in init
+            ? "CESR"
+            : (init.kind ?? "CESR");
+        if (this.kind === "list") {
+            try {
+                // Parser-origin list groups may be arbitrary generic list payloads, so
+                // deserialization into semantic aggregate elements is best-effort. When
+                // that semantic view is not meaningful we still preserve the structor.
+                this._ael = Aggor.deserializeList(this.qb64g, this.strict, this.saids);
+            }
+            catch {
+                this._ael = [];
+            }
+        }
+        else {
+            this._ael = [];
+        }
+    }
+    /** Aggregate identifier at element zero for list-form aggregates. */
+    get agid() {
+        return this.kind === "list" && typeof this._ael[0] === "string"
+            ? this._ael[0]
+            : null;
     }
-    /** Tuple/list payload items for aggregate-list families. */
+    /** Aggregate element list in semantic form. */
+    get ael() {
+        return this._ael.map((entry) => Aggor.clone(entry));
+    }
+    /** Tuple/list payload items for parser-origin list aggregate families. */
     get listItems() {
         return this.kind === "list" ? this.items : undefined;
     }
+    /**
+     * Verify that the disclosed aggregate list still hashes to the agid in slot zero.
+     *
+     * Example:
+     * a disclosure list like `[agid, {d: "...", x: 1}, "E...undisclosed"]`
+     * verifies when replacing the disclosed map with its computed SAID reproduces
+     * the agid at position zero.
+     */
+    static verifyDisclosure(ael, kind = "CESR", code = DigDex.Blake3_256, saids = { d: DigDex.Blake3_256 }) {
+        // Verification is intentionally "rebuild and compare agid", not a more
+        // magical shortcut. Disclosure semantics are easier to trust when the test
+        // is literally "does this disclosed list still hash back to slot zero?"
+        try {
+            const aggor = new Aggor({
+                ael,
+                kind,
+                code,
+                saids,
+                verify: true,
+            });
+            return aggor.agid === (typeof ael[0] === "string" ? ael[0] : null);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Produce a disclosure view where only `indices` are expanded back into maps.
+     *
+     * Index `0` is always the agid and stays compact; only later map elements are
+     * eligible for disclosure expansion.
+     */
+    disclose(indices = []) {
+        if (this.kind !== "list") {
+            throw new SerializeError("Disclosure is only defined for aggregate lists.");
+        }
+        // We first normalize every element into either:
+        // - the aggregate's compact commitment string, or
+        // - a `Mapper` that knows how to compute its own compact SAID.
+        const atoms = this._ael.map((element, index) => {
+            if (index === 0) {
+                return element;
+            }
+            if (element && typeof element === "object" && !Array.isArray(element)) {
+                return Mapper.fromSad(element, {
+                    strict: this.strict,
+                    saidive: true,
+                    saids: this.saids,
+                    kind: this.wireKind,
+                    makify: true,
+                    verify: false,
+                });
+            }
+            return element;
+        });
+        const disclosure = atoms.map((atom) => atom instanceof Mapper ? (atom.said ?? "") : atom);
+        for (const index of indices) {
+            if (index > 0 && index < atoms.length && atoms[index] instanceof Mapper) {
+                // Disclosure only expands selected post-agid map elements. The agid at
+                // slot zero always remains compact because it is the commitment anchor.
+                disclosure[index] = atoms[index].mad;
+            }
+        }
+        return [disclosure, this.wireKind];
+    }
     /** Hydrate from an already parsed counter-group node. */
     static fromGroup(group, sourceDomain = "txt") {
-        return new Aggor({ structor: Structor.fromGroup(group, sourceDomain) });
+        const structor = Structor.fromGroup(group, sourceDomain);
+        if (isAggorMapCode(structor.code)) {
+            const map = parseMapperBody(b(structor.qb64g), { major: 2, minor: 0 }, "txt");
+            return new Aggor({ structor, mapFields: map.fields });
+        }
+        return new Aggor({ structor });
+    }
+    static materializeStructor(init) {
+        const version = init.version ?? { major: 2, minor: 0 };
+        const raw = init.qb2
+            ? Aggor.canonicalize(init.qb2, version)
+            : init.qb64
+                ? b(init.qb64)
+                : init.qb64b
+                    ? init.qb64b
+                    : init.raw
+                        ? init.raw
+                        : init.ael
+                            ? b(Aggor.serializeList(Aggor.clone(init.ael), init))
+                            : null;
+        if (!raw) {
+            throw new SerializeError("Aggor requires ael or raw/qb64/qb64b/qb2 input.");
+        }
+        const structor = parseStructor(raw, version, "txt", AGGOR_CODES, "aggregate list/map");
+        const mapFields = isAggorMapCode(structor.code)
+            ? new Mapper({
+                raw: b(structor.qb64g),
+                version,
+                kind: "CESR",
+                verify: false,
+            }).fields
+            : undefined;
+        if (init.verify ?? true) {
+            if (isAggorListCode(structor.code)) {
+                // Today verification proves the aggregate identifier can be recomputed.
+                // It does not yet enforce every deeper KERIpy edge case, so keep this
+                // seam explicit for future parity expansion.
+                const ael = Aggor.deserializeList(structor.qb64g, init.strict ?? true, init.saids ?? { d: DigDex.Blake3_256 });
+                Aggor.computeAgid(ael, init.kind ?? "CESR", init.code ?? DigDex.Blake3_256, init.strict ?? true, init.saids ?? { d: DigDex.Blake3_256 });
+            }
+        }
+        return { structor, mapFields };
+    }
+    static canonicalize(raw, version) {
+        if (raw.length > 0 && raw[0] === "-".charCodeAt(0)) {
+            return raw;
+        }
+        const counter = parseCounter(raw, version, "bny");
+        return b(codeB2ToB64(raw, counter.fullSize + counter.count * 4));
+    }
+    static clone(value) {
+        if (Array.isArray(value)) {
+            return value.map((entry) => Aggor.clone(entry));
+        }
+        if (value && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, Aggor.clone(v)]));
+        }
+        return value;
+    }
+    static serializeList(ael, options) {
+        const strict = options.strict ?? true;
+        const saids = options.saids ?? { d: DigDex.Blake3_256 };
+        const kind = options.kind ?? "CESR";
+        const code = options.code ?? DigDex.Blake3_256;
+        const makify = options.makify ?? false;
+        const working = Aggor.clone(ael);
+        if (makify && working.length > 0) {
+            // Slot zero is always the aggregate identifier. During makify we dummy it
+            // first, normalize later map elements into saidified `Mapper`s, then
+            // compute the final agid over that compacted view.
+            const sizage = MATTER_SIZES.get(code);
+            if (!sizage?.fs) {
+                throw new SerializeError(`Unsupported aggregate digest code=${code}`);
+            }
+            working[0] = "#".repeat(sizage.fs);
+            for (let idx = 1; idx < working.length; idx++) {
+                const element = working[idx];
+                if (element && typeof element === "object" && !Array.isArray(element)) {
+                    const mapper = Mapper.fromSad(element, {
+                        strict,
+                        saidive: true,
+                        saids,
+                        kind,
+                        makify: true,
+                        verify: false,
+                    });
+                    working[idx] = mapper.mad;
+                }
+            }
+            const agid = Aggor.computeAgid(working, kind, code, strict, saids);
+            if (ael.length > 0) {
+                ael[0] = agid;
+            }
+        }
+        const compacted = working.map((element, idx) => {
+            if (idx === 0) {
+                return typeof ael[0] === "string" ? ael[0] : "";
+            }
+            if (element && typeof element === "object" && !Array.isArray(element)) {
+                // Aggregate list elements compact exactly like disclosed map sections:
+                // nested map content collapses to its mapper-native representation.
+                const mapper = Mapper.fromSad(element, {
+                    strict,
+                    saidive: true,
+                    saids,
+                    kind,
+                    makify: true,
+                    verify: false,
+                });
+                return mapper.qb64;
+            }
+            return String(element);
+        }).join("");
+        const codeName = compacted.length / 4 < 64 ** 2
+            ? CtrDexV2.GenericListGroup
+            : CtrDexV2.BigGenericListGroup;
+        return `${new Counter({ code: codeName, count: compacted.length / 4 }).qb64}${compacted}`;
+    }
+    static deserializeList(qb64, strict, saids) {
+        // Aggregate lists are walked element-by-element from the enclosed list
+        // payload. Elements may be:
+        // - compact qb64 commitments, or
+        // - nested map groups representing disclosed element bodies.
+        const raw = b(qb64);
+        const counter = parseCounter(raw, { major: 2, minor: 0 }, "txt");
+        const payload = raw.slice(counter.fullSize, counter.fullSize + counter.count * 4);
+        const out = [];
+        let offset = 0;
+        while (offset < payload.length) {
+            if (payload[offset] === "-".charCodeAt(0)) {
+                const nextCounter = parseCounter(payload.slice(offset), {
+                    major: 2,
+                    minor: 0,
+                }, "txt");
+                if (!isAggorMapCode(nextCounter.code)) {
+                    throw new DeserializeError(`Expected aggregate element map group, got ${nextCounter.code}`);
+                }
+                const total = nextCounter.fullSize + nextCounter.count * 4;
+                const mapper = new Mapper({
+                    raw: payload.slice(offset, offset + total),
+                    strict,
+                    saidive: true,
+                    saids,
+                    kind: "CESR",
+                    verify: false,
+                });
+                out.push(mapper.mad);
+                offset += total;
+                continue;
+            }
+            const matter = parseMatter(payload.slice(offset), "txt");
+            out.push(matter.qb64);
+            offset += matter.fullSize;
+        }
+        return out;
+    }
+    static computeAgid(ael, kind, code, strict, saids) {
+        // `agid` is computed over the compacted aggregate view:
+        // dummy slot zero, compact every nested map element to its mapper SAID, then
+        // hash the fully enclosed list-group serialization.
+        const compacted = ael.map((element, idx) => {
+            if (idx === 0) {
+                const sizage = MATTER_SIZES.get(code);
+                if (!sizage?.fs) {
+                    throw new SerializeError(`Unsupported aggregate digest code=${code}`);
+                }
+                return "#".repeat(sizage.fs);
+            }
+            if (element && typeof element === "object" && !Array.isArray(element)) {
+                const mapper = Mapper.fromSad(element, {
+                    strict,
+                    saidive: true,
+                    saids,
+                    kind,
+                    makify: true,
+                    verify: false,
+                });
+                return mapper.said ?? "";
+            }
+            return String(element);
+        }).join("");
+        const groupCode = compacted.length / 4 < 64 ** 2
+            ? CtrDexV2.GenericListGroup
+            : CtrDexV2.BigGenericListGroup;
+        const raw = b(`${new Counter({ code: groupCode, count: compacted.length / 4 }).qb64}${compacted}`);
+        return new Diger({ code, raw: Diger.digest(raw, code) }).qb64;
     }
 }
 /**
- * Parse aggregate attachment groups as list/map semantic containers.
+ * Parse aggregate attachment groups as semantic aggregate containers.
  *
- * KERIpy substance: aggregate counters can represent generic lists or map-body
- * structures; this helper normalizes both into one discriminated result.
+ * Example:
+ * a list body `-JAE<agid><map-or-said>...` becomes an `Aggor` whose `.ael`
+ * exposes the readable element list and whose `.agid` is the commitment in slot
+ * zero. A map-group still parses for compatibility, but exposes `.mapFields`
+ * rather than aggregate-list semantics.
  */
 export function parseAggor(input, version, cold) {
     const counter = parseCounter(input, version, cold);
     if (!isAggorCode(counter.code)) {
         throw new UnknownCodeError(`Expected aggregate list/map group code, got ${counter.code}`);
     }
-    const structor = parseStructor(input, version, cold, new Set([counter.code]), "aggregate list/map");
-    if (isAggorMapCode(structor.code)) {
-        const map = parseCompactor(input, version, cold);
-        return new Aggor({
-            structor,
-            mapFields: map.fields,
-        });
-    }
-    if (isAggorListCode(structor.code)) {
-        return new Aggor(structor);
-    }
-    throw new UnknownCodeError(`Expected aggregate list/map group code, got ${structor.code}`);
+    return new Aggor(cold === "txt"
+        ? { raw: input, version, kind: "CESR", verify: false }
+        : { qb2: input, version, kind: "CESR", verify: false });
 }

package/esm/src/primitives/bexter.js

@@ -38,12 +38,11 @@ export class Bexter extends Matter {
     static derawify(raw, code) {
         const ls = getLeadSize(code);
         const bext = encodeB64(new Uint8Array([...new Uint8Array(ls), ...raw]));
-        const ws = ls === 0 && bext.startsWith("A") ? 1 : (ls + 1) % 4;
+        const ws = ls === 0 ? (bext.startsWith("A") ? 1 : 0) : (ls + 1) % 4;
         return bext.slice(ws);
     }
     constructor(init) {
-        const matter = init instanceof Matter ? init : new Matter(init);
-        super(matter);
+        super(init);
         if (!isBexterCode(this.code)) {
             throw new UnknownCodeError(`Expected bexter strb64 code, got ${this.code}`);
         }

package/esm/src/primitives/blinder.js

@@ -10,6 +10,12 @@ export function isBlinderCode(code) {
  *
  * KERIpy substance: `Blinder` materializes blinded/bound state tuple groups
  * used for blindable ACDC/TEL state disclosures.
+ *
+ * Maintainer note:
+ * - this class owns counted-group transport framing only
+ * - semantic blind/unblind/commit helpers live in `disclosure.ts`
+ * - the semantic fixed-field records carried by these groups are
+ *   `BlindState` and `BoundState` from `structing.ts`
  */
 export class Blinder extends Structor {
     constructor(init) {

package/esm/src/primitives/byte-like.js

@@ -0,0 +1,19 @@
+import { b } from "../core/bytes.js";
+/** Normalize text or buffer-view inputs into one detached `Uint8Array`. */
+export function normalizeByteLike(value) {
+    if (typeof value === "string") {
+        return b(value);
+    }
+    if (value instanceof Uint8Array) {
+        return Object.getPrototypeOf(value) === Uint8Array.prototype
+            ? value.slice()
+            : new Uint8Array(value);
+    }
+    return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+}
+/** Runtime guard for byte-like primitive constructor inputs. */
+export function isByteLike(value) {
+    return typeof value === "string"
+        || value instanceof Uint8Array
+        || ArrayBuffer.isView(value);
+}

package/esm/src/primitives/cigar.js

@@ -6,18 +6,32 @@ import { Matter, parseMatter } from "./matter.js";
  *
  * KERIpy substance: `Cigar` wraps detached signature material where code
  * determines signature suite and payload holds raw signature bytes.
+ *
+ * Runtime note:
+ * - `.verfer` is contextual verifier metadata attached by signing, dispatch,
+ *   or DB-rehydration code
+ * - it is not encoded inside the cigar bytes themselves
  */
 export class Cigar extends Matter {
-    constructor(init) {
-        const matter = init instanceof Matter ? init : new Matter(init);
-        super(matter);
+    constructor(init, verfer) {
+        super(init);
+        /** Optional verifier context for the key that created this detached signature. */
+        Object.defineProperty(this, "verfer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         if (!CIGAR_CODES.has(this.code)) {
             throw new UnknownCodeError(`Expected non-indexed signature code, got ${this.code}`);
         }
+        this.verfer = verfer;
     }
+    /** Raw detached signature bytes. */
     get sig() {
         return this.raw;
     }
+    /** Human-oriented generated codex member name for diagnostics and tooling. */
     get algorithm() {
         return matterCodexName(this.code) ?? "UnknownSig";
     }

package/esm/src/primitives/cipher.js

@@ -1,18 +1,103 @@
-import { UnknownCodeError } from "../core/errors.js";
-import { CIPHER_X25519_ALL_CODES } from "./codex.js";
+import { DeserializeError, UnknownCodeError } from "../core/errors.js";
+import { normalizeByteLike } from "./byte-like.js";
+import { CiXDex } from "./codex.js";
+import { CIPHER_X25519_ALL_CODES, MtrDex } from "./codex.js";
+import { Decrypter } from "./decrypter.js";
 import { Matter } from "./matter.js";
+/** Map the KERIpy fixed cipher families to their expected raw sealed-box sizes. */
+function expectedFixedCipherRawSize(code) {
+    return Matter.rawSizeForCode(code);
+}
+const FIXED_RAW_SIZES = new Map([
+    [
+        MtrDex.X25519_Cipher_Seed,
+        expectedFixedCipherRawSize(MtrDex.X25519_Cipher_Seed),
+    ],
+    [
+        MtrDex.X25519_Cipher_Salt,
+        expectedFixedCipherRawSize(MtrDex.X25519_Cipher_Salt),
+    ],
+]);
+function inferFixedCipherCode(raw) {
+    for (const [code, size] of FIXED_RAW_SIZES.entries()) {
+        if (raw.length === size) {
+            return code;
+        }
+    }
+    throw new DeserializeError(`Unsupported fixed raw size ${raw.length} for X25519 cipher material.`);
+}
+/**
+ * Support KERIpy's convenience rule where fixed cipher families may be
+ * inferred from raw ciphertext size when the caller omits `code`.
+ */
+function normalizeCipherInit(init) {
+    if (init instanceof Matter || !init.raw) {
+        return init;
+    }
+    const normalized = {
+        ...init,
+        raw: init.raw.slice(),
+    };
+    if (!normalized.code) {
+        normalized.code = inferFixedCipherCode(normalized.raw);
+    }
+    return normalized;
+}
 /**
  * Ciphertext primitive for encrypted secret payloads.
  *
- * KERIpy substance: cipher material carries encrypted seed/salt-like plaintext
- * while code determines ciphertext family/size semantics.
+ * KERIpy substance: cipher material carries sealed-box encrypted CESR payloads
+ * while the cipher code preserves how the plaintext should be rehydrated.
+ *
+ * Construction rule:
+ * - fixed salt/seed cipher families may infer `code` from raw size
+ * - variable families still require the caller or parser to provide the
+ *   correct derivation code explicitly
  */
 export class Cipher extends Matter {
     constructor(init) {
-        const matter = init instanceof Matter ? init : new Matter(init);
-        super(matter);
+        super(normalizeCipherInit(init));
         if (!CIPHER_X25519_ALL_CODES.has(this.code)) {
             throw new UnknownCodeError(`Expected cipher code, got ${this.code}`);
         }
     }
+    /**
+     * Recover plaintext from this cipher using either a box private key or seed.
+     *
+     * KERIpy parity:
+     * - `prikey` or `seed` instantiates a `Decrypter`
+     * - default plaintext constructor is inferred from the cipher family when
+     *   possible
+     *
+     * Key-material rule:
+     * - `prikey` is already-qualified X25519 private box material
+     * - `seed` is an Ed25519 signer seed that is first converted into the
+     *   corresponding X25519 private box key
+     */
+    decrypt({ prikey, seed, ctor, transferable = false, bare = false, } = {}) {
+        return new Decrypter({
+            qb64: typeof prikey === "string" ? prikey : undefined,
+            qb64b: prikey && typeof prikey !== "string"
+                ? normalizeByteLike(prikey)
+                : undefined,
+            seed,
+        }).decrypt({
+            cipher: this,
+            ctor,
+            transferable,
+            bare,
+        });
+    }
 }
+Object.defineProperty(Cipher, "Codex", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: CiXDex
+});
+Object.defineProperty(Cipher, "Codes", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: Object.freeze({ ...CiXDex })
+});