@motebit/crypto 2.0.0 → 3.0.0

package/dist/merkle.d.ts

@@ -13,6 +13,54 @@
  *   - `witness-omission-dispute.ts` — `inclusion_proof` evidence
  *     against a horizon cert's `federation_graph_anchor.merkle_root`.
  */
+import type { MerkleTreeVersion } from "@motebit/protocol";
+/**
+ * Hash a Merkle leaf under a tree-hash version — the single dispatch point for
+ * the RFC 6962 §2.1 leaf-domain `0x00` tag, the leaf-side mirror of the
+ * interior-node `0x01` tag applied in {@link verifyMerkleInclusion}'s combine
+ * step. v1 = `SHA-256(entry)`; v2 = `SHA-256(0x00 ‖ entry)`. Every leaf builder
+ * (settlement, credential, identity-log, consolidation) routes its leaf hash
+ * through here, so the leaf tag lives in exactly one place — the
+ * `check-suite-dispatch` shape applied to the Merkle axis (locked by
+ * `check-merkle-tree-hash-canonical`).
+ *
+ * Producer-side contract: THROWS on a version this primitive does not implement
+ * (a builder asking for an unregistered version is a programming error, not
+ * untrusted input — unlike the verifier path, which returns `false`). The
+ * high-level verifiers validate the proof's `tree_hash_version` at their own
+ * boundary before threading it down, so an unhandled value never reaches here
+ * from untrusted input.
+ *
+ * @param entry - the leaf's entry bytes (e.g. encoded `canonicalJson(record)`)
+ * @param treeHashVersion - tree-hash recipe; default `merkle-sha256-plain-v1`
+ * @returns hex-encoded SHA-256 leaf hash
+ */
+export declare function hashLeaf(entry: Uint8Array, treeHashVersion?: MerkleTreeVersion): Promise<string>;
+/**
+ * JCS-canonicalize a value, then leaf-hash it via {@link hashLeaf}.
+ * `canonicalLeaf(x)` (v1 default) is byte-identical to `canonicalSha256(x)` —
+ * the leaf builders that used the latter keep their v1 output unchanged while
+ * gaining the v2 path for free. The shared canonicalization means a producer
+ * and a holder who hold the same object derive the identical leaf.
+ *
+ * @param value - the object the leaf commits to (signature included for signed artifacts)
+ * @param treeHashVersion - tree-hash recipe; default `merkle-sha256-plain-v1`
+ * @returns hex-encoded SHA-256 leaf hash
+ */
+export declare function canonicalLeaf(value: unknown, treeHashVersion?: MerkleTreeVersion): Promise<string>;
+/**
+ * Resolve a proof's wire `tree_hash_version` string to a `MerkleTreeVersion` at
+ * a verifier boundary. **Absent ⇒ `merkle-sha256-plain-v1`** (never silently
+ * upgraded — threat-model rule a); a known value passes through; an UNKNOWN
+ * string returns `null` so the caller fails closed and REJECTS (never downgrades
+ * to v1 — threat-model rule b). The leaf-builder + Merkle-inclusion calls
+ * downstream then receive a narrow, supported version. Mirrors the
+ * `verifyBySuite` suite-resolution contract, one axis over. The two string
+ * literals here are the verifier-side dispatch arms the closed-registry gate
+ * (`check-merkle-tree-hash-canonical`) keeps aligned with
+ * `ALL_MERKLE_TREE_VERSIONS`.
+ */
+export declare function resolveTreeHashVersion(raw: string | undefined): MerkleTreeVersion | null;
 /**
  * Verify a Merkle inclusion proof against an expected root.
  *
@@ -24,11 +72,19 @@
  * Returns `false` on any malformed input or hash mismatch — never
  * throws. Same fail-closed contract as `verifyBySuite`.
  *
+ * The `leaf` is the already-computed bottom-layer leaf HASH; the leaf-domain
+ * `0x00` tag (RFC 6962 §2.1) lives in the leaf builders that produce it, so this
+ * primitive applies only the interior-node `0x01` tag (under v2). `absent ⇒ v1`
+ * is resolved by the caller (the high-level verifier reads the proof's
+ * `tree_hash_version`); the default here keeps the ~dozen existing 5-arg callers
+ * byte-identical (v1) until they thread a version.
+ *
  * @param leaf - hex-encoded SHA-256 leaf hash
  * @param index - leaf position in the bottom layer (0-based)
  * @param siblings - hex-encoded sibling hashes, leaf-to-root order
  * @param layerSizes - bottom-up layer cardinalities
  * @param expectedRoot - hex-encoded SHA-256 root the proof must reconstruct
+ * @param treeHashVersion - tree-hash recipe; default `merkle-sha256-plain-v1`
  */
-export declare function verifyMerkleInclusion(leaf: string, index: number, siblings: string[], layerSizes: number[], expectedRoot: string): Promise<boolean>;
+export declare function verifyMerkleInclusion(leaf: string, index: number, siblings: string[], layerSizes: number[], expectedRoot: string, treeHashVersion?: MerkleTreeVersion): Promise<boolean>;
 //# sourceMappingURL=merkle.d.ts.map

package/dist/merkle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyBH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,EAAE,MAAM,EAAE,EACpB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,CAiClB"}
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA0B3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,UAAU,EACjB,eAAe,GAAE,iBAA4C,GAC5D,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,eAAe,GAAE,iBAA4C,GAC5D,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,GAAG,IAAI,CAIxF;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,EAAE,MAAM,EAAE,EACpB,YAAY,EAAE,MAAM,EACpB,eAAe,GAAE,iBAA4C,GAC5D,OAAO,CAAC,OAAO,CAAC,CA8ClB"}

package/dist/signing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,wBAAwB,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAG,wBAAiC,CAAC;AAIpE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAclD;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAMlD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMpD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQrD;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAczD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAoBvD;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAezD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAS/D;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE;AAID,wBAAsB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAED,gEAAgE;AAChE,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAGlE;AAaD,OAAO,EACL,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAExD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,EAC1C,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAoCpC;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQxD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAehF"}
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,wBAAwB,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAG,wBAAiC,CAAC;AAIpE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAclD;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAMlD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMpD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQrD;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAczD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAoBvD;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAezD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAS/D;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE;AAID,wBAAsB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAED,gEAAgE;AAChE,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAGlE;AAaD,OAAO,EACL,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAExD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,EAC1C,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAoCpC;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQxD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAehF"}

package/dist/suite-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suite-dispatch.d.ts","sourceRoot":"","sources":["../src/suite-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAkBH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AASjD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,UAAU,EAC1B,cAAc,EAAE,UAAU,EAC1B,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,UAAU,EAC1B,eAAe,EAAE,UAAU,GAC1B,OAAO,CAAC,UAAU,CAAC,CASrB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,sBAAsB,IAAI,OAAO,CAAC;IACtD,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC,CAGD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CASrB;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,sBAAsB,EAAE,MAAM,EAC9B,YAAY,EAAE,UAAU,EACxB,iBAAiB,EAAE,UAAU,GAC5B,OAAO,CAQT"}
+{"version":3,"file":"suite-dispatch.d.ts","sourceRoot":"","sources":["../src/suite-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAoBH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAcjD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,UAAU,EAC1B,cAAc,EAAE,UAAU,EAC1B,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,UAAU,EAC1B,eAAe,EAAE,UAAU,GAC1B,OAAO,CAAC,UAAU,CAAC,CASrB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,sBAAsB,IAAI,OAAO,CAAC;IACtD,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC,CAGD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CASrB;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,sBAAsB,EAAE,MAAM,EAC9B,YAAY,EAAE,UAAU,EACxB,iBAAiB,EAAE,UAAU,GAC5B,OAAO,CAUT"}