@peac/audit 0.16.1 → 0.16.2

package/dist/merkle.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @peac/audit - Merkle commitment helpers for workflow receipt sets.
+ *
+ * Executes the deferred WORKFLOW-CORRELATION section 7 Merkle commitment as
+ * deterministic, offline helpers. This is a CT-style Merkle Tree Hash following
+ * the RFC 9162 section 2.1.1 formulas (RFC 9162 obsoletes RFC 6962), adapted as
+ * a sorted-set commitment over PEAC `receipt_ref` digests. It is NOT a
+ * Certificate Transparency append-only log and PEAC does not operate a log or
+ * anchor these roots anywhere.
+ *
+ * Proves inclusion in the committed set; it does NOT prove chronology,
+ * completeness, payment finality, payment validity, privacy, or legal validity.
+ * Callers must still verify each PEAC record independently.
+ *
+ * Inputs are `receipt_ref` strings (`sha256:<hex64>`, DD-129) only. Callers that
+ * start from compact JWS bytes use `@peac/schema` `computeReceiptRef(jws)` first;
+ * this module does not re-implement digest computation.
+ */
+import type { ReceiptRef } from '@peac/kernel';
+/** Algorithm identifier for this sorted-set commitment construction. */
+export declare const MERKLE_TREE_ALG: "peac.merkle.ct-sorted-set-sha256-v1";
+/** Hash algorithm used for leaves and internal nodes. */
+export declare const MERKLE_HASH_ALG: "sha256";
+/**
+ * A `sha256:<hex64>` digest reference. Shares its grammar with `ReceiptRef` but
+ * carries different semantics (a Merkle hash, not a PEAC record reference).
+ */
+export type Sha256DigestRef = `sha256:${string}`;
+/** A Merkle root digest (NOT a receipt reference). */
+export type ReceiptMerkleRoot = Sha256DigestRef;
+/** A Merkle inclusion-proof sibling hash (NOT a receipt reference). */
+export type MerkleNodeHash = Sha256DigestRef;
+/** Self-describing commitment over a sorted set of receipt references. */
+export interface ReceiptMerkleCommitment {
+    readonly tree_alg: typeof MERKLE_TREE_ALG;
+    readonly hash_alg: typeof MERKLE_HASH_ALG;
+    readonly root: ReceiptMerkleRoot;
+    readonly tree_size: number;
+}
+/** Inclusion proof for a single receipt reference against a committed root. */
+export interface ReceiptMerkleInclusionProof {
+    readonly tree_alg: typeof MERKLE_TREE_ALG;
+    readonly hash_alg: typeof MERKLE_HASH_ALG;
+    /** Index of the target within the SORTED leaf order. */
+    readonly leaf_index: number;
+    readonly tree_size: number;
+    /** Sibling path, leaf -> root order, each `sha256:<hex64>`. */
+    readonly hashes: readonly MerkleNodeHash[];
+}
+export type MerkleInputErrorCode = 'audit.merkle.empty_input' | 'audit.merkle.invalid_receipt_ref' | 'audit.merkle.duplicate_receipt_ref' | 'audit.merkle.target_not_found' | 'audit.merkle.invalid_commitment' | 'audit.merkle.invalid_merkle_root' | 'audit.merkle.invalid_proof' | 'audit.merkle.invalid_proof_hash' | 'audit.merkle.unsupported_tree_alg' | 'audit.merkle.unsupported_hash_alg';
+/**
+ * Thrown ONLY on malformed input (bad grammar, empty/duplicate input,
+ * unsupported algorithm, out-of-range index, target not found). A well-formed
+ * but cryptographically wrong proof returns `false` from
+ * {@link verifyReceiptMerkleInclusion} and does not throw. These are
+ * package-local errors; they are not kernel protocol errors.
+ */
+export declare class MerkleInputError extends Error {
+    readonly code: MerkleInputErrorCode;
+    constructor(code: MerkleInputErrorCode, message: string);
+}
+/**
+ * Build a Merkle commitment over a sorted set of receipt references.
+ *
+ * Rejects empty input and duplicate refs. The returned `root`/`tree_size` map
+ * directly to a workflow summary's `receipt_merkle_root`/`receipt_count`.
+ * @throws {MerkleInputError} on empty input, malformed ref, or duplicate ref.
+ */
+export declare function buildReceiptMerkleCommitment(refs: readonly ReceiptRef[]): ReceiptMerkleCommitment;
+/**
+ * Generate an offline inclusion proof for `targetRef` against the committed set.
+ * `leaf_index` in the returned proof is the index within the SORTED leaf order.
+ * @throws {MerkleInputError} on empty input, malformed ref, duplicate ref, or
+ * when `targetRef` is not present in `refs`.
+ */
+export declare function generateReceiptMerkleInclusionProof(refs: readonly ReceiptRef[], targetRef: ReceiptRef): ReceiptMerkleInclusionProof;
+/**
+ * Verify an inclusion proof offline against a full commitment.
+ *
+ * Verifying against the {@link ReceiptMerkleCommitment} (not a naked root) binds
+ * the proof to the commitment's `tree_size` as well as its `root`, so a proof
+ * whose `tree_size` disagrees with the commitment is rejected up front.
+ *
+ * Returns `false` for a well-formed but cryptographically wrong proof (wrong
+ * root, wrong sibling, wrong target, mismatched tree_size, truncated/extra path).
+ * @throws {MerkleInputError} on malformed input: a structurally invalid
+ * commitment/proof, bad root/target/sibling grammar, unsupported
+ * `tree_alg`/`hash_alg`, or non-integer/out-of-range `leaf_index`/`tree_size`.
+ */
+export declare function verifyReceiptMerkleInclusion(commitment: ReceiptMerkleCommitment, targetRef: ReceiptRef, proof: ReceiptMerkleInclusionProof): boolean;
+//# sourceMappingURL=merkle.d.ts.map

package/dist/merkle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,wEAAwE;AACxE,eAAO,MAAM,eAAe,EAAG,qCAA8C,CAAC;AAC9E,yDAAyD;AACzD,eAAO,MAAM,eAAe,EAAG,QAAiB,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,MAAM,EAAE,CAAC;AACjD,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAChD,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAE7C,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,eAAe,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,eAAe,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,eAAe,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,eAAe,CAAC;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,oBAAoB,GAC5B,0BAA0B,GAC1B,kCAAkC,GAClC,oCAAoC,GACpC,+BAA+B,GAC/B,iCAAiC,GACjC,kCAAkC,GAClC,4BAA4B,GAC5B,iCAAiC,GACjC,mCAAmC,GACnC,mCAAmC,CAAC;AAExC;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;gBACxB,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAKxD;AA8LD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,uBAAuB,CAQjG;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,SAAS,EAAE,UAAU,GACpB,2BAA2B,CAiB7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,uBAAuB,EACnC,SAAS,EAAE,UAAU,EACrB,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAqET"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/audit",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Audit logging and case bundle generation for PEAC protocol disputes",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -30,9 +30,9 @@
   "dependencies": {
     "yazl": "^3.3.1",
     "yauzl": "^2.10.0",
-    "@peac/crypto": "0.16.1",
-    "@peac/schema": "0.16.1",
-    "@peac/kernel": "0.16.1"
+    "@peac/kernel": "0.16.2",
+    "@peac/crypto": "0.16.2",
+    "@peac/schema": "0.16.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",