@unrdf/observability 26.4.2

package/src/receipts/merkle-tree.mjs

@@ -0,0 +1,188 @@
+/**
+ * Merkle Tree - Efficient batch verification for receipts
+ *
+ * Builds binary Merkle tree over receipt hashes:
+ * - O(log n) proof size for n receipts
+ * - Single root hash for batch verification
+ * - Efficient proof generation and verification
+ *
+ * @module @unrdf/observability/receipts/merkle-tree
+ */
+
+import { blake3 } from 'hash-wasm';
+import { MerkleProofSchema } from './receipt-schema.mjs';
+
+/**
+ * MerkleTree - Binary Merkle tree for receipt batching
+ *
+ * @example
+ * const tree = new MerkleTree();
+ * tree.addReceipt(receipt1);
+ * tree.addReceipt(receipt2);
+ * const root = await tree.buildTree();
+ * const proof = await tree.generateProof(receipt1.id);
+ */
+export class MerkleTree {
+  /**
+   * Create a new Merkle tree
+   */
+  constructor() {
+    this.receipts = [];
+    this.leaves = [];
+    this.tree = [];
+    this.root = null;
+  }
+
+  /**
+   * Add receipt to tree (before building)
+   * @param {Object} receipt - Receipt to add
+   */
+  addReceipt(receipt) {
+    if (!receipt || !receipt.id || !receipt.hash) {
+      throw new TypeError('addReceipt: receipt must have id and hash');
+    }
+    this.receipts.push(receipt);
+    this.root = null; // Invalidate tree
+  }
+
+  /**
+   * Build Merkle tree from receipts
+   * @returns {Promise<string>} Merkle root hash (64-char hex)
+   */
+  async buildTree() {
+    if (this.receipts.length === 0) {
+      throw new Error('Cannot build tree: no receipts added');
+    }
+
+    // Initialize leaves from receipt hashes
+    this.leaves = this.receipts.map(r => r.hash);
+    this.tree = [this.leaves];
+
+    // Build tree levels
+    let currentLevel = this.leaves;
+    while (currentLevel.length > 1) {
+      const nextLevel = [];
+      let i = 0;
+      while (i < currentLevel.length) {
+        if (i + 1 < currentLevel.length) {
+          // Hash pair
+          const left = currentLevel[i];
+          const right = currentLevel[i + 1];
+          const combined = left + ':' + right;
+          const pairHash = await blake3(combined);
+          nextLevel.push(pairHash);
+          i += 2;
+        } else {
+          // Odd node promoted to next level
+          nextLevel.push(currentLevel[i]);
+          i += 1;
+        }
+      }
+      this.tree.push(nextLevel);
+      currentLevel = nextLevel;
+    }
+
+    this.root = currentLevel[0];
+    return this.root;
+  }
+
+  /**
+   * Get Merkle root
+   * @returns {string|null}
+   */
+  getRoot() {
+    return this.root;
+  }
+
+  /**
+   * Generate Merkle proof for a receipt
+   *
+   * @param {string} receiptId - Receipt ID to prove
+   * @returns {Promise<Object>} Merkle proof
+   * @throws {Error} If receipt not found or tree not built
+   */
+  async generateProof(receiptId) {
+    if (!this.root) {
+      throw new Error('Tree not built: call buildTree() first');
+    }
+
+    const index = this.receipts.findIndex(r => r.id === receiptId);
+    if (index === -1) {
+      throw new Error('Receipt not found: ' + receiptId);
+    }
+
+    const receipt = this.receipts[index];
+    const siblings = [];
+
+    let idx = index;
+    let level = 0;
+    while (level < this.tree.length - 1) {
+      const levelData = this.tree[level];
+      const siblingIdx = idx % 2 === 0 ? idx + 1 : idx - 1;
+
+      if (siblingIdx < levelData.length) {
+        siblings.push({
+          hash: levelData[siblingIdx],
+          position: idx % 2 === 0 ? 'right' : 'left',
+        });
+      }
+
+      idx = Math.floor(idx / 2);
+      level += 1;
+    }
+
+    const proof = {
+      receiptId: receipt.id,
+      receiptHash: receipt.hash,
+      root: this.root,
+      siblings,
+      index,
+    };
+
+    return MerkleProofSchema.parse(proof);
+  }
+
+  /**
+   * Verify a Merkle proof
+   *
+   * @param {Object} proof - Merkle proof to verify
+   * @returns {Promise<boolean>} Whether proof is valid
+   */
+  async verifyProof(proof) {
+    try {
+      MerkleProofSchema.parse(proof);
+    } catch (err) {
+      return false;
+    }
+
+    let currentHash = proof.receiptHash;
+
+    let i = 0;
+    while (i < proof.siblings.length) {
+      const sibling = proof.siblings[i];
+      const combined =
+        sibling.position === 'right'
+          ? currentHash + ':' + sibling.hash
+          : sibling.hash + ':' + currentHash;
+      currentHash = await blake3(combined);
+      i += 1;
+    }
+
+    return currentHash === proof.root;
+  }
+
+  /**
+   * Get tree info
+   * @returns {Object} Tree metadata
+   */
+  getTreeInfo() {
+    return {
+      receiptCount: this.receipts.length,
+      depth: this.tree.length - 1,
+      root: this.root,
+      leafCount: this.leaves.length,
+    };
+  }
+}
+
+export default MerkleTree;

package/src/receipts/receipt-chain.mjs

@@ -0,0 +1,209 @@
+/**
+ * Receipt Chain - Hash-chained receipt sequence
+ *
+ * Provides immutable audit trail via hash chaining:
+ * - Each receipt contains hash of previous receipt
+ * - Chain break detection (any modification invalidates subsequent hashes)
+ * - Temporal ordering enforcement
+ * - Complete provenance from genesis to current
+ *
+ * @module @unrdf/observability/receipts/receipt-chain
+ */
+
+import { blake3 } from 'hash-wasm';
+import { ReceiptSchema } from './receipt-schema.mjs';
+
+/**
+ * ReceiptChain - Manages a chain of cryptographically linked receipts
+ *
+ * @example
+ * const chain = new ReceiptChain('audit-chain-1');
+ * await chain.append({
+ *   operation: 'admit',
+ *   payload: { delta: 'delta_001' },
+ *   actor: 'system'
+ * });
+ */
+export class ReceiptChain {
+  /**
+   * Create a new receipt chain
+   * @param {string} chainId - Unique chain identifier
+   */
+  constructor(chainId) {
+    if (!chainId || typeof chainId !== 'string') {
+      throw new TypeError('ReceiptChain requires a string chainId');
+    }
+    this.chainId = chainId;
+    this.receipts = [];
+    this.lastTimestamp = 0n;
+  }
+
+  /**
+   * Get chain length
+   * @returns {number}
+   */
+  get length() {
+    return this.receipts.length;
+  }
+
+  /**
+   * Get latest receipt
+   * @returns {Object|null}
+   */
+  getLatest() {
+    return this.receipts.length > 0 ? this.receipts[this.receipts.length - 1] : null;
+  }
+
+  /**
+   * Generate deterministic receipt ID
+   * @param {string} operation - Operation type
+   * @param {bigint} timestamp - Timestamp in nanoseconds
+   * @returns {string}
+   * @private
+   */
+  _generateId(operation, timestamp) {
+    return `receipt-${operation}-${timestamp}-${this.receipts.length}`;
+  }
+
+  /**
+   * Compute canonical hash of receipt content
+   * @param {Object} content - Receipt content to hash
+   * @returns {Promise<string>} BLAKE3 hash (64-char hex)
+   * @private
+   */
+  async _computeHash(content) {
+    // Canonical JSON serialization (sorted keys)
+    const canonical = JSON.stringify(content, Object.keys(content).sort());
+    return await blake3(canonical);
+  }
+
+  /**
+   * Append a new receipt to the chain
+   *
+   * @param {Object} receiptData - Receipt data
+   * @param {string} receiptData.operation - Operation type
+   * @param {any} receiptData.payload - Operation payload
+   * @param {string} [receiptData.actor] - Actor who performed operation
+   * @param {bigint} [receiptData.timestamp_ns] - Custom timestamp (default: now)
+   * @param {Object} [receiptData.metadata] - Optional metadata
+   * @returns {Promise<Object>} Appended receipt
+   * @throws {Error} If receipt is invalid or chain is broken
+   */
+  async append(receiptData) {
+    const { operation, payload, actor, metadata } = receiptData;
+
+    // Input validation
+    if (!operation || typeof operation !== 'string') {
+      throw new TypeError('append: operation must be a non-empty string');
+    }
+    if (payload === undefined || payload === null) {
+      throw new TypeError('append: payload is required');
+    }
+
+    // Get timestamp (custom or now)
+    const timestamp_ns = receiptData.timestamp_ns || BigInt(Date.now()) * 1_000_000n;
+
+    // Enforce monotonic time
+    if (timestamp_ns <= this.lastTimestamp) {
+      throw new Error(`Timestamp not monotonic: ${timestamp_ns} <= ${this.lastTimestamp}`);
+    }
+
+    // Generate receipt ID
+    const id = this._generateId(operation, timestamp_ns);
+    const timestamp_iso = new Date(Number(timestamp_ns / 1_000_000n)).toISOString();
+
+    // Get previous receipt hash (or null for genesis)
+    const previousHash = this.getLatest()?.hash || null;
+
+    // Build canonical receipt object for hashing
+    const canonicalContent = {
+      id,
+      timestamp_ns: timestamp_ns.toString(),
+      timestamp_iso,
+      operation,
+      payload,
+      previousHash,
+      ...(actor && { actor }),
+      ...(metadata && { metadata }),
+    };
+
+    // Compute hash
+    const hash = await this._computeHash(canonicalContent);
+
+    // Create receipt
+    const receipt = {
+      id,
+      hash,
+      timestamp_ns: timestamp_ns.toString(),
+      timestamp_iso,
+      operation,
+      payload,
+      previousHash,
+      ...(actor && { actor }),
+      ...(metadata && { metadata }),
+    };
+
+    // Validate against schema
+    const validated = ReceiptSchema.parse(receipt);
+
+    // Append to chain
+    this.receipts.push(Object.freeze(validated));
+    this.lastTimestamp = timestamp_ns;
+
+    return validated;
+  }
+
+  /**
+   * Get receipt by index
+   * @param {number} index - Receipt index (0-based)
+   * @returns {Object|null}
+   */
+  getReceipt(index) {
+    return this.receipts[index] || null;
+  }
+
+  /**
+   * Get receipt by ID
+   * @param {string} id - Receipt ID
+   * @returns {Object|null}
+   */
+  getReceiptById(id) {
+    return this.receipts.find(r => r.id === id) || null;
+  }
+
+  /**
+   * Get all receipts (defensive copy)
+   * @returns {Array<Object>}
+   */
+  getAllReceipts() {
+    return [...this.receipts];
+  }
+
+  /**
+   * Serialize chain to JSON
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      chainId: this.chainId,
+      length: this.receipts.length,
+      receipts: this.receipts,
+    };
+  }
+
+  /**
+   * Deserialize chain from JSON
+   * @param {Object} json - Serialized chain
+   * @returns {ReceiptChain}
+   */
+  static fromJSON(json) {
+    const chain = new ReceiptChain(json.chainId);
+    for (const receipt of json.receipts) {
+      chain.receipts.push(Object.freeze(receipt));
+      chain.lastTimestamp = BigInt(receipt.timestamp_ns);
+    }
+    return chain;
+  }
+}
+
+export default ReceiptChain;

package/src/receipts/receipt-schema.mjs

@@ -0,0 +1,128 @@
+/**
+ * Receipt Schema Definitions
+ *
+ * Zod schemas for tamper-evident receipt system
+ * Supports hash chaining, merkle proofs, and external anchoring
+ *
+ * @module @unrdf/observability/receipts/receipt-schema
+ */
+
+import { z } from 'zod';
+
+/**
+ * Receipt schema - cryptographic proof of an operation
+ *
+ * Fields:
+ * - id: Unique receipt identifier (UUID or deterministic)
+ * - hash: BLAKE3 hash of receipt content (64-char hex)
+ * - timestamp_ns: Nanosecond timestamp (BigInt as string)
+ * - timestamp_iso: ISO 8601 timestamp for human readability
+ * - operation: Operation type ('admit', 'freeze', 'publish', etc.)
+ * - payload: Operation-specific data (any JSON)
+ * - previousHash: Hash of previous receipt (null for genesis)
+ * - actor: Who performed the operation
+ * - metadata: Optional additional metadata
+ */
+export const ReceiptSchema = z.object({
+  id: z.string().min(1),
+  hash: z.string().regex(/^[0-9a-f]{64}$/i, 'Must be 64-character hex hash'),
+  timestamp_ns: z.string().regex(/^\d+$/, 'Must be numeric string'),
+  timestamp_iso: z.string().datetime(),
+  operation: z.string().min(1),
+  payload: z.any(),
+  previousHash: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/i)
+    .nullable(),
+  actor: z.string().min(1).optional(),
+  metadata: z.record(z.any()).optional(),
+});
+
+/**
+ * Merkle proof schema - proves receipt inclusion in tree
+ */
+export const MerkleProofSchema = z.object({
+  receiptId: z.string(),
+  receiptHash: z.string().regex(/^[0-9a-f]{64}$/i),
+  root: z.string().regex(/^[0-9a-f]{64}$/i),
+  siblings: z.array(
+    z.object({
+      hash: z.string().regex(/^[0-9a-f]{64}$/i),
+      position: z.enum(['left', 'right']),
+    })
+  ),
+  index: z.number().int().nonnegative(),
+});
+
+/**
+ * Anchor schema - external timestamping/anchoring proof
+ */
+export const AnchorSchema = z.object({
+  merkleRoot: z.string().regex(/^[0-9a-f]{64}$/i),
+  anchorType: z.enum(['blockchain', 'git', 'timestamp-service']),
+  anchorData: z.object({
+    // Blockchain
+    txHash: z.string().optional(),
+    blockNumber: z.number().optional(),
+    network: z.string().optional(),
+    // Git
+    commitSha: z.string().optional(),
+    repository: z.string().optional(),
+    // Timestamp service
+    timestampToken: z.string().optional(),
+    authority: z.string().optional(),
+  }),
+  timestamp: z.string().datetime(),
+});
+
+/**
+ * Verification result schema
+ */
+export const VerificationResultSchema = z.object({
+  valid: z.boolean(),
+  receiptId: z.string().optional(),
+  errors: z.array(z.string()).default([]),
+  checks: z
+    .object({
+      hashIntegrity: z.boolean().optional(),
+      chainLink: z.boolean().optional(),
+      temporalOrder: z.boolean().optional(),
+      merkleProof: z.boolean().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * Chain export schema - audit trail export
+ */
+export const ChainExportSchema = z.object({
+  chainId: z.string(),
+  receiptCount: z.number().int().nonnegative(),
+  firstReceipt: z.string().datetime().optional(),
+  lastReceipt: z.string().datetime().optional(),
+  merkleRoot: z.string().regex(/^[0-9a-f]{64}$/i),
+  chainValid: z.boolean(),
+  receipts: z.array(ReceiptSchema),
+  exportedAt: z.string().datetime(),
+  anchor: AnchorSchema.optional(),
+});
+
+/**
+ * Type exports for TypeScript/JSDoc
+ */
+
+/**
+ * @typedef {z.infer<typeof ReceiptSchema>} Receipt
+ * @typedef {z.infer<typeof MerkleProofSchema>} MerkleProof
+ * @typedef {z.infer<typeof AnchorSchema>} Anchor
+ * @typedef {z.infer<typeof VerificationResultSchema>} VerificationResult
+ * @typedef {z.infer<typeof ChainExportSchema>} ChainExport
+ */
+
+export default {
+  ReceiptSchema,
+  MerkleProofSchema,
+  AnchorSchema,
+  VerificationResultSchema,
+  ChainExportSchema,
+};