@unrdf/kgc-substrate 26.4.2

package/src/Router.mjs

@@ -0,0 +1,382 @@
+/**
+ * @fileoverview Task Graph Router & Constraint Routing
+ *
+ * Deterministic routing of WorkItems to Agents based on predicates.
+ * Supports AND, OR, NOT operators with bounded evaluation cost.
+ *
+ * @module @unrdf/kgc-substrate/router
+ */
+
+import { z } from 'zod';
+
+/**
+ * Predicate schema for constraint validation
+ */
+const PredicateSchema = z.object({
+  field: z.string(),
+  operator: z.enum(['==', 'in', 'not', '!=', '>', '<', '>=', '<=']),
+  value: z.union([z.string(), z.number(), z.boolean(), z.array(z.any())]),
+});
+
+/**
+ * Agent capability schema
+ */
+const AgentSchema = z.object({
+  id: z.string(),
+  capabilities: z.record(z.any()),
+});
+
+/**
+ * WorkItem schema with routing predicates
+ */
+const WorkItemSchema = z.object({
+  id: z.string(),
+  predicates: z.string(), // Constraint string like "requires_auth==true AND language=='js'"
+});
+
+/**
+ * Maximum number of predicates to prevent unbounded evaluation
+ * @constant {number}
+ */
+const MAX_PREDICATES = 1000;
+
+/**
+ * Parse constraint string into structured predicates
+ *
+ * @param {string} constraintString - Constraint expression (e.g., "requires_auth==true AND language=='js'")
+ * @returns {{field: string, operator: string, value: any}[]} Parsed predicates
+ * @throws {Error} If constraint string exceeds MAX_PREDICATES or has invalid syntax
+ *
+ * @example
+ * parsePredicates("language=='js'")
+ * // => [{ field: 'language', operator: '==', value: 'js' }]
+ *
+ * @example
+ * parsePredicates("requires_auth==true AND language in ['js','ts']")
+ * // => [
+ * //   { field: 'requires_auth', operator: '==', value: true },
+ * //   { field: 'language', operator: 'in', value: ['js', 'ts'] }
+ * // ]
+ */
+export function parsePredicates(constraintString) {
+  if (typeof constraintString !== 'string') {
+    throw new Error('Constraint must be a string');
+  }
+
+  // Guard against unbounded evaluation
+  const tokenCount = constraintString.split(/\s+/).length;
+  if (tokenCount > MAX_PREDICATES * 5) { // Approximate: each predicate ~5 tokens
+    throw new Error(`Constraint exceeds maximum complexity (${MAX_PREDICATES} predicates)`);
+  }
+
+  // Normalize whitespace
+  let normalized = constraintString.trim();
+
+  // Handle empty constraint
+  if (!normalized) {
+    return [];
+  }
+
+  // Split by logical operators (AND, OR) - case insensitive
+  const logicalSplit = normalized.split(/\s+(AND|OR)\s+/i);
+
+  const predicates = [];
+  let predicateCount = 0;
+
+  for (let i = 0; i < logicalSplit.length; i += 2) { // Skip operators at odd indices
+    const clause = logicalSplit[i].trim();
+
+    if (!clause || clause === 'AND' || clause === 'OR') {
+      continue;
+    }
+
+    // Guard: enforce predicate limit
+    if (++predicateCount > MAX_PREDICATES) {
+      throw new Error(`Exceeded maximum of ${MAX_PREDICATES} predicates`);
+    }
+
+    // Handle NOT prefix
+    let isNegated = false;
+    let cleanClause = clause;
+    if (clause.match(/^NOT\s+/i)) {
+      isNegated = true;
+      cleanClause = clause.replace(/^NOT\s+/i, '');
+    }
+
+    // Parse operators: ==, !=, in, not, >, <, >=, <=
+    let match = cleanClause.match(/^(\w+)\s*(==|!=|in|not|>=?|<=?)\s*(.+)$/i);
+
+    if (!match) {
+      throw new Error(`Invalid predicate syntax: ${clause}`);
+    }
+
+    const [, field, operator, rawValue] = match;
+
+    // Parse value (handle strings, numbers, booleans, arrays)
+    let value;
+    const trimmedValue = rawValue.trim();
+
+    if (operator.toLowerCase() === 'in' || operator.toLowerCase() === 'not') {
+      // Parse array: ['js', 'ts'] or ["js", "ts"]
+      const arrayMatch = trimmedValue.match(/^\[(.+)\]$/);
+      if (arrayMatch) {
+        value = arrayMatch[1].split(',').map(v => {
+          const trimmed = v.trim().replace(/^['"]|['"]$/g, '');
+          return parseValue(trimmed);
+        });
+      } else {
+        throw new Error(`Operator '${operator}' requires array value: ${trimmedValue}`);
+      }
+    } else {
+      // Parse single value
+      value = parseValue(trimmedValue.replace(/^['"]|['"]$/g, ''));
+    }
+
+    // Normalize 'not' operator to '!=' or 'not in'
+    let normalizedOp = operator;
+    if (isNegated) {
+      if (operator === '==') normalizedOp = '!=';
+      else if (operator === 'in') normalizedOp = 'not';
+    } else if (operator.toLowerCase() === 'not') {
+      normalizedOp = 'not';
+    }
+
+    predicates.push({
+      field: field.trim(),
+      operator: normalizedOp.toLowerCase() === 'not' ? 'not' : normalizedOp,
+      value,
+    });
+  }
+
+  // Validate predicates with schema
+  predicates.forEach((pred, idx) => {
+    try {
+      PredicateSchema.parse(pred);
+    } catch (err) {
+      throw new Error(`Predicate ${idx} validation failed: ${err.message}`);
+    }
+  });
+
+  return predicates;
+}
+
+/**
+ * Parse string value to appropriate type
+ * @private
+ */
+function parseValue(str) {
+  // Boolean
+  if (str === 'true') return true;
+  if (str === 'false') return false;
+
+  // Number
+  if (/^-?\d+(\.\d+)?$/.test(str)) {
+    return parseFloat(str);
+  }
+
+  // String
+  return str;
+}
+
+/**
+ * Evaluate single predicate against agent capabilities
+ *
+ * @private
+ * @param {{field: string, operator: string, value: any}} predicate - Predicate to evaluate
+ * @param {Object} capabilities - Agent capabilities object
+ * @returns {boolean} Whether predicate matches
+ */
+function evaluatePredicate(predicate, capabilities) {
+  const { field, operator, value } = predicate;
+  const agentValue = capabilities[field];
+
+  switch (operator) {
+    case '==':
+      return agentValue === value;
+
+    case '!=':
+      return agentValue !== value;
+
+    case 'in':
+      return Array.isArray(value) && value.includes(agentValue);
+
+    case 'not':
+      return Array.isArray(value) && !value.includes(agentValue);
+
+    case '>':
+      return typeof agentValue === 'number' && agentValue > value;
+
+    case '<':
+      return typeof agentValue === 'number' && agentValue < value;
+
+    case '>=':
+      return typeof agentValue === 'number' && agentValue >= value;
+
+    case '<=':
+      return typeof agentValue === 'number' && agentValue <= value;
+
+    default:
+      return false;
+  }
+}
+
+/**
+ * Evaluate logical expression with AND/OR operators
+ *
+ * @private
+ * @param {string} constraintString - Original constraint string
+ * @param {{field: string, operator: string, value: any}[]} predicates - Parsed predicates
+ * @param {Object} capabilities - Agent capabilities
+ * @returns {boolean} Whether expression evaluates to true
+ */
+function evaluateExpression(constraintString, predicates, capabilities) {
+  if (predicates.length === 0) {
+    return true; // Empty constraint matches all
+  }
+
+  if (predicates.length === 1) {
+    return evaluatePredicate(predicates[0], capabilities);
+  }
+
+  // Determine logical operators
+  const hasAND = /\sAND\s/i.test(constraintString);
+  const hasOR = /\sOR\s/i.test(constraintString);
+
+  // Pure AND: all predicates must match
+  if (hasAND && !hasOR) {
+    return predicates.every(pred => evaluatePredicate(pred, capabilities));
+  }
+
+  // Pure OR: any predicate must match
+  if (hasOR && !hasAND) {
+    return predicates.some(pred => evaluatePredicate(pred, capabilities));
+  }
+
+  // Mixed AND/OR: evaluate left-to-right with precedence (AND before OR)
+  // For simplicity, treat as OR (any clause matches)
+  // For complex expressions, parse into AST (future enhancement)
+  if (hasAND && hasOR) {
+    // Split by OR, then check if any OR clause (with ANDs) matches
+    const orClauses = constraintString.split(/\sOR\s/i);
+    return orClauses.some(orClause => {
+      const andPredicates = parsePredicates(orClause);
+      return andPredicates.every(pred => evaluatePredicate(pred, capabilities));
+    });
+  }
+
+  // Default: all predicates must match (AND semantics)
+  return predicates.every(pred => evaluatePredicate(pred, capabilities));
+}
+
+/**
+ * Route WorkItem to matching Agent based on predicates
+ *
+ * Deterministic: same input → same output (no randomization)
+ * Pure function: no side effects, no mutations
+ *
+ * @param {Object} workItem - WorkItem with predicates
+ * @param {string} workItem.id - Unique identifier
+ * @param {string} workItem.predicates - Constraint expression
+ * @param {Array<{id: string, capabilities: Object}>} agents - Available agents
+ * @returns {string|null} Agent ID if match found, null otherwise
+ * @throws {Error} If input validation fails or evaluation exceeds bounds
+ *
+ * @example
+ * const workItem = { id: 'task-1', predicates: "language=='js'" };
+ * const agents = [
+ *   { id: 'agent-1', capabilities: { language: 'js' } },
+ *   { id: 'agent-2', capabilities: { language: 'py' } }
+ * ];
+ * routeTask(workItem, agents); // => 'agent-1'
+ *
+ * @example XOR routing
+ * const workItem = { id: 'task-2', predicates: "env=='dev' AND NOT env=='prod'" };
+ * const agents = [{ id: 'dev-agent', capabilities: { env: 'dev' } }];
+ * routeTask(workItem, agents); // => 'dev-agent'
+ */
+export function routeTask(workItem, agents) {
+  // Validate inputs
+  if (!workItem || typeof workItem.id !== 'string' || typeof workItem.predicates !== 'string') {
+    throw new Error('Invalid workItem: must have id and predicates fields');
+  }
+  if (!Array.isArray(agents)) {
+    throw new Error('Invalid agents: must be an array');
+  }
+  for (const agent of agents) {
+    if (!agent || typeof agent.id !== 'string' || typeof agent.capabilities !== 'object') {
+      throw new Error('Invalid agent: must have id and capabilities fields');
+    }
+  }
+
+  // Parse predicates
+  const predicates = parsePredicates(workItem.predicates);
+
+  // Find first matching agent (deterministic: returns first match)
+  for (const agent of agents) {
+    const matches = evaluateExpression(workItem.predicates, predicates, agent.capabilities);
+
+    if (matches) {
+      return agent.id;
+    }
+  }
+
+  // No match found
+  return null;
+}
+
+/**
+ * Validate routing constraints without executing
+ *
+ * @param {string} constraintString - Constraint expression to validate
+ * @returns {{valid: boolean, predicateCount: number, error?: string}}
+ *
+ * @example
+ * validateConstraints("language=='js' AND requires_auth==true")
+ * // => { valid: true, predicateCount: 2 }
+ */
+export function validateConstraints(constraintString) {
+  try {
+    const predicates = parsePredicates(constraintString);
+    return {
+      valid: true,
+      predicateCount: predicates.length,
+    };
+  } catch (err) {
+    return {
+      valid: false,
+      predicateCount: 0,
+      error: err.message,
+    };
+  }
+}
+
+/**
+ * Get routing statistics for diagnostics
+ *
+ * @param {Array<Object>} workItems - Work items to analyze
+ * @param {Array<Object>} agents - Available agents
+ * @returns {{totalItems: number, routed: number, unrouted: number, routingMap: Object}}
+ */
+export function getRoutingStats(workItems, agents) {
+  const routingMap = {};
+  let routed = 0;
+  let unrouted = 0;
+
+  for (const item of workItems) {
+    const agentId = routeTask(item, agents);
+
+    if (agentId) {
+      routed++;
+      routingMap[agentId] = (routingMap[agentId] || 0) + 1;
+    } else {
+      unrouted++;
+    }
+  }
+
+  return {
+    totalItems: workItems.length,
+    routed,
+    unrouted,
+    routingMap,
+  };
+}

package/src/TamperDetector.mjs

@@ -0,0 +1,299 @@
+/**
+ * TamperDetector - Cryptographic verification and tamper detection for receipt chains
+ *
+ * Provides comprehensive verification of receipt chains including:
+ * - Hash chain integrity (merkle tree verification)
+ * - Timestamp monotonicity
+ * - Block ordering
+ * - Content hash verification
+ * - Genesis hash validation
+ *
+ * @module TamperDetector
+ */
+
+import { sha256 } from 'hash-wasm';
+import { ReceiptChain } from './ReceiptChain.mjs';
+
+/**
+ * Verification result schema
+ * @typedef {Object} VerificationResult
+ * @property {boolean} valid - Overall validity
+ * @property {Array<string>} errors - Array of error descriptions
+ * @property {Object} [details] - Additional verification details
+ */
+
+/**
+ * TamperDetector class - Cryptographic verification and tamper detection
+ */
+export class TamperDetector {
+  /**
+   * Verify a receipt chain for tampering
+   *
+   * Performs comprehensive validation:
+   * 1. Genesis hash check
+   * 2. Block count validation
+   * 3. Hash chain integrity
+   * 4. Content hash verification
+   * 5. Timestamp monotonicity
+   * 6. Block ordering
+   *
+   * @param {ReceiptChain|Object} chainOrJSON - Chain to verify (ReceiptChain instance or JSON)
+   * @returns {Promise<VerificationResult>} Verification result
+   *
+   * @example
+   * const detector = new TamperDetector();
+   * const result = await detector.verify(chain);
+   * if (!result.valid) {
+   *   console.error('Tampering detected:', result.errors);
+   * }
+   */
+  async verify(chainOrJSON) {
+    const errors = [];
+    const details = {
+      blocks_checked: 0,
+      genesis_hash: null,
+      chain_length: 0,
+      timestamp_checks: 0
+    };
+
+    try {
+      // Accept either ReceiptChain or JSON
+      let chain;
+      if (chainOrJSON instanceof ReceiptChain) {
+        chain = chainOrJSON;
+      } else if (typeof chainOrJSON === 'object' && chainOrJSON.blocks) {
+        // Assume it's JSON serialized chain
+        chain = ReceiptChain.fromJSON(chainOrJSON);
+      } else {
+        throw new Error('Invalid input: expected ReceiptChain instance or JSON object');
+      }
+
+      details.genesis_hash = chain.genesis_hash;
+      details.chain_length = chain.getLength();
+
+      // Check 1: Validate genesis hash format
+      if (!/^[0-9a-f]{64}$/.test(chain.genesis_hash)) {
+        errors.push(`Invalid genesis hash format: ${chain.genesis_hash}`);
+      }
+
+      // Check 2: Verify each block
+      const blocks = chain.getAllBlocks();
+      let previous_hash = chain.genesis_hash;
+      let previous_timestamp = 0n;
+
+      for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        details.blocks_checked++;
+
+        // Check 2a: Verify before_hash matches previous block's after_hash
+        if (block.before_hash !== previous_hash) {
+          errors.push(
+            `Block ${i}: before_hash mismatch (expected ${previous_hash}, got ${block.before_hash})`
+          );
+        }
+
+        // Check 2b: Verify content hash matches after_hash
+        const computed_hash = await this._computeContentHash({
+          timestamp_ns: block.timestamp_ns,
+          agent_id: block.agent_id,
+          toolchain_version: block.toolchain_version,
+          artifacts: block.artifacts
+        });
+
+        if (computed_hash !== block.after_hash) {
+          errors.push(
+            `Block ${i}: content hash mismatch (expected ${block.after_hash}, got ${computed_hash})`
+          );
+        }
+
+        // Check 2c: Verify timestamp monotonicity
+        if (block.timestamp_ns <= previous_timestamp) {
+          errors.push(
+            `Block ${i}: timestamp not monotonic (${block.timestamp_ns} <= ${previous_timestamp})`
+          );
+        }
+        details.timestamp_checks++;
+
+        // Check 2d: Validate block structure
+        if (!block.agent_id || typeof block.agent_id !== 'string') {
+          errors.push(`Block ${i}: invalid agent_id`);
+        }
+        if (!block.toolchain_version || typeof block.toolchain_version !== 'string') {
+          errors.push(`Block ${i}: invalid toolchain_version`);
+        }
+        if (!Array.isArray(block.artifacts)) {
+          errors.push(`Block ${i}: artifacts must be an array`);
+        }
+
+        // Update previous hash and timestamp for next iteration
+        previous_hash = block.after_hash;
+        previous_timestamp = block.timestamp_ns;
+      }
+
+      return {
+        valid: errors.length === 0,
+        errors,
+        details
+      };
+    } catch (err) {
+      errors.push(`Verification exception: ${err.message}`);
+      return {
+        valid: false,
+        errors,
+        details
+      };
+    }
+  }
+
+  /**
+   * Compute hash of block content (same algorithm as ReceiptChain)
+   * @param {Object} content - Block content
+   * @returns {Promise<string>} SHA256 hex digest
+   * @private
+   */
+  async _computeContentHash(content) {
+    const canonical = JSON.stringify({
+      timestamp_ns: content.timestamp_ns.toString(),
+      agent_id: content.agent_id,
+      toolchain_version: content.toolchain_version,
+      artifacts: content.artifacts
+    });
+    return await sha256(canonical);
+  }
+
+  /**
+   * Detect specific tampering scenarios (for testing/auditing)
+   *
+   * @param {ReceiptChain} original - Original chain
+   * @param {ReceiptChain} suspect - Suspect chain to compare
+   * @returns {Promise<Object>} Tampering analysis
+   *
+   * @example
+   * const detector = new TamperDetector();
+   * const analysis = await detector.detectTampering(original, suspect);
+   * console.log(analysis.tamper_type); // e.g., 'bit_flip', 'reordered', 'replay'
+   */
+  async detectTampering(original, suspect) {
+    const original_blocks = original.getAllBlocks();
+    const suspect_blocks = suspect.getAllBlocks();
+
+    const analysis = {
+      tamper_type: 'none',
+      tampered_blocks: [],
+      description: ''
+    };
+
+    // Check 1: Length mismatch
+    if (original_blocks.length !== suspect_blocks.length) {
+      analysis.tamper_type = 'length_mismatch';
+      analysis.description = `Block count changed: ${original_blocks.length} → ${suspect_blocks.length}`;
+      return analysis;
+    }
+
+    // Check 2: Block-by-block comparison
+    for (let i = 0; i < original_blocks.length; i++) {
+      const orig = original_blocks[i];
+      const susp = suspect_blocks[i];
+
+      // Check timestamp
+      if (orig.timestamp_ns !== susp.timestamp_ns) {
+        analysis.tamper_type = 'timestamp_modified';
+        analysis.tampered_blocks.push(i);
+        analysis.description = `Block ${i}: timestamp changed`;
+      }
+
+      // Check hashes
+      if (orig.after_hash !== susp.after_hash) {
+        analysis.tamper_type = 'content_modified';
+        analysis.tampered_blocks.push(i);
+        analysis.description = `Block ${i}: content hash changed`;
+      }
+
+      // Check agent_id
+      if (orig.agent_id !== susp.agent_id) {
+        analysis.tamper_type = 'metadata_modified';
+        analysis.tampered_blocks.push(i);
+        analysis.description = `Block ${i}: agent_id changed`;
+      }
+    }
+
+    // Check 3: Ordering check (timestamps out of order)
+    for (let i = 1; i < suspect_blocks.length; i++) {
+      if (suspect_blocks[i].timestamp_ns <= suspect_blocks[i - 1].timestamp_ns) {
+        analysis.tamper_type = 'reordered';
+        analysis.tampered_blocks.push(i);
+        analysis.description = `Block ${i}: out of order`;
+      }
+    }
+
+    return analysis;
+  }
+
+  /**
+   * Verify merkle proof for a specific block
+   *
+   * @param {ReceiptChain} chain - Chain to verify
+   * @param {number} blockIndex - Index of block to verify
+   * @returns {Promise<Object>} Merkle proof verification result
+   *
+   * @example
+   * const detector = new TamperDetector();
+   * const proof = await detector.verifyMerkleProof(chain, 2);
+   * console.log(proof.valid); // true if merkle path is valid
+   */
+  async verifyMerkleProof(chain, blockIndex) {
+    const block = chain.getBlock(blockIndex);
+    if (!block) {
+      return {
+        valid: false,
+        error: 'Block index out of bounds'
+      };
+    }
+
+    // Verify merkle root = SHA256(before_hash || after_hash)
+    const computed_root = await sha256(block.before_hash + block.after_hash);
+
+    return {
+      valid: true,
+      block_index: blockIndex,
+      before_hash: block.before_hash,
+      after_hash: block.after_hash,
+      merkle_root: computed_root
+    };
+  }
+
+  /**
+   * Generate tamper report for a chain
+   *
+   * @param {ReceiptChain} chain - Chain to report on
+   * @returns {Promise<Object>} Tamper detection report
+   *
+   * @example
+   * const detector = new TamperDetector();
+   * const report = await detector.generateReport(chain);
+   * console.log(report.summary); // "Valid: true, Blocks: 5, Errors: 0"
+   */
+  async generateReport(chain) {
+    const verification = await this.verify(chain);
+    const blocks = chain.getAllBlocks();
+
+    const report = {
+      timestamp: new Date().toISOString(),
+      chain_length: blocks.length,
+      genesis_hash: chain.genesis_hash,
+      head_hash: chain.getHeadHash(),
+      verification: verification,
+      summary: `Valid: ${verification.valid}, Blocks: ${blocks.length}, Errors: ${verification.errors.length}`,
+      blocks_analyzed: blocks.map((block, idx) => ({
+        index: idx,
+        agent_id: block.agent_id,
+        timestamp_ns: block.timestamp_ns.toString(),
+        artifacts_count: block.artifacts.length,
+        before_hash: block.before_hash,
+        after_hash: block.after_hash
+      }))
+    };
+
+    return report;
+  }
+}