@longarc/mdash 3.0.0

package/src/core/commitment.ts

@@ -0,0 +1,438 @@
+/**
+ * mdash v3.0 - Commitment Layer (L1)
+ * 
+ * Sub-millisecond cryptographic commitments.
+ * "The seal races the attack."
+ * 
+ * Target Latency:
+ * - Commitment seal: <0.5ms P50, <1ms P99
+ * - Merkle proof: <0.1ms
+ */
+
+import {
+  Hash,
+  Seal,
+  Timestamp,
+  sha256,
+  sha256Object,
+  rollingHash,
+  hmacSeal,
+  hmacVerify,
+  deriveKey,
+  generateTimestamp,
+  constantTimeEqual,
+} from './crypto';
+
+// ============================================================================
+// COMMITMENT TYPES
+// ============================================================================
+
+export interface Commitment {
+  /** Unique commitment identifier */
+  id: string;
+  /** Operation ID this commitment is associated with */
+  operationId?: string;
+  /** SHA-256 hash of the committed content */
+  content_hash: Hash;
+  /** Timestamp of commitment creation */
+  committed_at: Timestamp;
+  /** HMAC seal binding id + hash + timestamp */
+  seal: Seal;
+  /** Protocol version for upgrade path */
+  version: 'v3.0';
+}
+
+export interface CommitmentProof {
+  /** The commitment being proven */
+  commitment: Commitment;
+  /** Merkle path from leaf to root */
+  merkle_path: MerklePathNode[];
+  /** Root hash at time of commitment */
+  root_hash: Hash;
+  /** Position in the tree (leaf index) */
+  leaf_index: number;
+}
+
+export interface MerklePathNode {
+  /** Hash value */
+  hash: Hash;
+  /** Position: 'left' or 'right' relative to current node */
+  position: 'left' | 'right';
+}
+
+// ============================================================================
+// MERKLE TREE - Incremental for streaming support
+// ============================================================================
+
+export class IncrementalMerkleTree {
+  private leaves: Hash[] = [];
+  private levels: Hash[][] = [];
+  private readonly maxDepth: number;
+  
+  constructor(maxDepth: number = 20) {
+    this.maxDepth = maxDepth;
+  }
+  
+  /**
+   * Add a leaf to the tree
+   * O(log n) operation
+   */
+  async addLeaf(hash: Hash): Promise<number> {
+    const index = this.leaves.length;
+    
+    if (index >= Math.pow(2, this.maxDepth)) {
+      throw new Error(`Tree capacity exceeded: max ${Math.pow(2, this.maxDepth)} leaves`);
+    }
+    
+    this.leaves.push(hash);
+    await this.updatePath(index);
+    
+    return index;
+  }
+  
+  /**
+   * Update the Merkle path for a new leaf
+   * Incrementally updates only affected nodes
+   */
+  private async updatePath(leafIndex: number): Promise<void> {
+    const leafHash = this.leaves[leafIndex];
+    if (!leafHash) {
+      throw new Error(`Leaf not found at index ${leafIndex}`);
+    }
+    let currentHash: Hash = leafHash;
+    let currentIndex = leafIndex;
+    
+    for (let level = 0; level < this.maxDepth; level++) {
+      const levelArray = this.levels[level] ?? (this.levels[level] = []);
+      
+      const siblingIndex = currentIndex ^ 1; // XOR to get sibling
+      const parentIndex = currentIndex >> 1; // Divide by 2
+      
+      // Get sibling hash (empty hash if doesn't exist)
+      const siblingHash: Hash = levelArray[siblingIndex] ?? await sha256('');
+      
+      // Store current hash at this level
+      levelArray[currentIndex] = currentHash;
+      
+      // Compute parent hash
+      if (currentIndex % 2 === 0) {
+        currentHash = await rollingHash([currentHash, siblingHash]);
+      } else {
+        currentHash = await rollingHash([siblingHash, currentHash]);
+      }
+      
+      currentIndex = parentIndex;
+    }
+  }
+  
+  /**
+   * Get the current root hash
+   */
+  async getRoot(): Promise<Hash> {
+    if (this.leaves.length === 0) {
+      return sha256('empty');
+    }
+    
+    // Root is at the top level
+    const topLevel = this.levels[this.maxDepth - 1];
+    return topLevel?.[0] || await sha256('');
+  }
+  
+  /**
+   * Generate Merkle proof for a leaf
+   * O(log n) operation
+   */
+  async getProof(leafIndex: number): Promise<MerklePathNode[]> {
+    if (leafIndex < 0 || leafIndex >= this.leaves.length) {
+      throw new Error(`Invalid leaf index: ${leafIndex}`);
+    }
+    
+    const path: MerklePathNode[] = [];
+    let currentIndex = leafIndex;
+    
+    for (let level = 0; level < this.maxDepth; level++) {
+      const siblingIndex = currentIndex ^ 1;
+      const levelArray = this.levels[level];
+      const siblingHash: Hash = levelArray?.[siblingIndex] ?? await sha256('');
+      
+      path.push({
+        hash: siblingHash,
+        position: currentIndex % 2 === 0 ? 'right' : 'left',
+      });
+      
+      currentIndex = currentIndex >> 1;
+    }
+    
+    return path;
+  }
+  
+  /**
+   * Verify a Merkle proof
+   * O(log n) operation
+   */
+  static async verifyProof(
+    leafHash: Hash,
+    proof: MerklePathNode[],
+    expectedRoot: Hash
+  ): Promise<boolean> {
+    let currentHash = leafHash;
+    
+    for (const node of proof) {
+      if (node.position === 'left') {
+        currentHash = await rollingHash([node.hash, currentHash]);
+      } else {
+        currentHash = await rollingHash([currentHash, node.hash]);
+      }
+    }
+    
+    return constantTimeEqual(currentHash, expectedRoot);
+  }
+  
+  /**
+   * Get tree statistics
+   */
+  getStats(): { leaves: number; depth: number; capacity: number } {
+    return {
+      leaves: this.leaves.length,
+      depth: Math.ceil(Math.log2(this.leaves.length + 1)),
+      capacity: Math.pow(2, this.maxDepth),
+    };
+  }
+}
+
+// ============================================================================
+// COMMITMENT ENGINE
+// ============================================================================
+
+export class CommitmentEngine {
+  private key: CryptoKey | null = null;
+  private tree: IncrementalMerkleTree;
+  private commitments: Map<string, Commitment> = new Map();
+  
+  constructor(maxTreeDepth: number = 20) {
+    this.tree = new IncrementalMerkleTree(maxTreeDepth);
+  }
+  
+  /**
+   * Initialize the engine with a seal key
+   */
+  async initialize(sealKey: string): Promise<void> {
+    this.key = await deriveKey(sealKey);
+  }
+  
+  /**
+   * Create a commitment for content
+   * Target: <0.5ms P50, <1ms P99
+   */
+  async commit<T>(content: T, id: string): Promise<Commitment> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const startTime = performance.now();
+    
+    // Hash the content
+    const contentHash = await sha256Object(content);
+    const timestamp = generateTimestamp();
+    
+    // Create the commitment record
+    const commitmentData = {
+      _v: 1, // Protocol version for upgrade path
+      id,
+      content_hash: contentHash,
+      committed_at: timestamp,
+    };
+    
+    // Seal the commitment
+    const seal = await hmacSeal(commitmentData, this.key);
+    
+    const commitment: Commitment = {
+      id,
+      content_hash: contentHash,
+      committed_at: timestamp,
+      seal,
+      version: 'v3.0',
+    };
+    
+    // Add to Merkle tree
+    await this.tree.addLeaf(contentHash);
+    
+    // Store commitment
+    this.commitments.set(id, commitment);
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 1) {
+      console.warn(`Commitment latency exceeded P99: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return commitment;
+  }
+  
+  /**
+   * Get a commitment by ID
+   */
+  getCommitment(id: string): Commitment | undefined {
+    return this.commitments.get(id);
+  }
+  
+  /**
+   * Verify a commitment
+   */
+  async verify(commitment: Commitment): Promise<boolean> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const commitmentData = {
+      _v: 1,
+      id: commitment.id,
+      content_hash: commitment.content_hash,
+      committed_at: commitment.committed_at,
+    };
+    
+    return hmacVerify(commitmentData, commitment.seal, this.key);
+  }
+  
+  /**
+   * Generate a proof for a commitment
+   */
+  async generateProof(id: string): Promise<CommitmentProof> {
+    const commitment = this.commitments.get(id);
+    if (!commitment) {
+      throw new Error(`Commitment not found: ${id}`);
+    }
+    
+    // Find leaf index
+    const leafIndex = Array.from(this.commitments.keys()).indexOf(id);
+    
+    const merkle_path = await this.tree.getProof(leafIndex);
+    const root_hash = await this.tree.getRoot();
+    
+    return {
+      commitment,
+      merkle_path,
+      root_hash,
+      leaf_index: leafIndex,
+    };
+  }
+  
+  /**
+   * Verify a proof
+   */
+  async verifyProof(proof: CommitmentProof): Promise<boolean> {
+    // First verify the commitment seal
+    const commitmentValid = await this.verify(proof.commitment);
+    if (!commitmentValid) {
+      return false;
+    }
+    
+    // Then verify the Merkle path
+    return IncrementalMerkleTree.verifyProof(
+      proof.commitment.content_hash,
+      proof.merkle_path,
+      proof.root_hash
+    );
+  }
+  
+  /**
+   * Get the current Merkle root
+   */
+  async getRoot(): Promise<Hash> {
+    return this.tree.getRoot();
+  }
+  
+  /**
+   * Get statistics
+   */
+  getStats(): {
+    commitments: number;
+    treeStats: { leaves: number; depth: number; capacity: number };
+  } {
+    return {
+      commitments: this.commitments.size,
+      treeStats: this.tree.getStats(),
+    };
+  }
+}
+
+// ============================================================================
+// LATENCY MONITORING
+// ============================================================================
+
+export interface LatencyMetrics {
+  operation: string;
+  p50_ms: number;
+  p99_ms: number;
+  count: number;
+  breaches: number;
+}
+
+export class LatencyMonitor {
+  private metrics: Map<string, number[]> = new Map();
+  private thresholds: Map<string, { p50: number; p99: number }> = new Map();
+  
+  constructor() {
+    // Default thresholds from v3.0 spec
+    this.thresholds.set('commitment_seal', { p50: 0.5, p99: 1 });
+    this.thresholds.set('merkle_proof', { p50: 0.05, p99: 0.1 });
+    this.thresholds.set('context_chunk_seal', { p50: 2, p99: 5 });
+    this.thresholds.set('checkpoint_create', { p50: 0.5, p99: 1 });
+  }
+  
+  /**
+   * Record a latency sample
+   */
+  record(operation: string, latencyMs: number): void {
+    if (!this.metrics.has(operation)) {
+      this.metrics.set(operation, []);
+    }
+    this.metrics.get(operation)!.push(latencyMs);
+  }
+  
+  /**
+   * Get metrics for an operation
+   */
+  getMetrics(operation: string): LatencyMetrics | null {
+    const samples = this.metrics.get(operation);
+    if (!samples || samples.length === 0) {
+      return null;
+    }
+    
+    const sorted = [...samples].sort((a, b) => a - b);
+    const p50Index = Math.floor(sorted.length * 0.5);
+    const p99Index = Math.floor(sorted.length * 0.99);
+    
+    const threshold = this.thresholds.get(operation);
+    const p50 = sorted[p50Index] ?? 0;
+    const p99 = sorted[p99Index] ?? 0;
+    
+    return {
+      operation,
+      p50_ms: p50,
+      p99_ms: p99,
+      count: samples.length,
+      breaches: threshold ? samples.filter(s => s > threshold.p99).length : 0,
+    };
+  }
+  
+  /**
+   * Check if operation is within SLA
+   */
+  isWithinSLA(operation: string): boolean {
+    const metrics = this.getMetrics(operation);
+    const threshold = this.thresholds.get(operation);
+    
+    if (!metrics || !threshold) {
+      return true;
+    }
+    
+    return metrics.p99_ms <= threshold.p99;
+  }
+  
+  /**
+   * Clear metrics
+   */
+  clear(): void {
+    this.metrics.clear();
+  }
+}