@veraxhq/verax 0.2.1 → 0.4.0

package/src/cli/util/digest-engine.js

@@ -0,0 +1,359 @@
+/**
+ * Digest Engine
+ * Produces cryptographic hashes of run artifacts for determinism proof
+ * Ensures two identical runs produce identical digests
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Normalize JSON for hashing (canonicalize)
+ * Removes volatile fields, sorts keys consistently
+ */
+function normalizeJSON(obj, volatileFields = []) {
+  if (typeof obj !== 'object' || obj === null) {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => normalizeJSON(item, volatileFields));
+  }
+
+  const normalized = {};
+  const keys = Object.keys(obj).sort();
+
+  for (const key of keys) {
+    // Skip volatile fields
+    if (volatileFields.some(field => key.includes(field))) {
+      continue;
+    }
+
+    const value = obj[key];
+    if (typeof value === 'object' && value !== null) {
+      normalized[key] = normalizeJSON(value, volatileFields);
+    } else {
+      normalized[key] = value;
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Strip timestamps and volatile data from string content
+ */
+function stripVolatile(content) {
+  if (typeof content !== 'string') {
+    return content;
+  }
+
+  let cleaned = content;
+
+  // Strip ISO timestamps
+  cleaned = cleaned.replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[.Z0-9]*/g, '[TIMESTAMP]');
+
+  // Strip UUIDs
+  cleaned = cleaned.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '[UUID]');
+
+  // Strip run IDs (format: YYYY-MM-DDTHH-MM-SSZ_XXXXXX)
+  cleaned = cleaned.replace(/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z_[a-z0-9]+/gi, '[RUN_ID]');
+
+  // Strip execution times (durations)
+  cleaned = cleaned.replace(/"endedAt":\s*"[^"]*"/g, '"endedAt":"[TIMESTAMP]"');
+  cleaned = cleaned.replace(/"startedAt":\s*"[^"]*"/g, '"startedAt":"[TIMESTAMP]"');
+  cleaned = cleaned.replace(/"observedAt":\s*"[^"]*"/g, '"observedAt":"[TIMESTAMP]"');
+
+  // Strip finding IDs
+  cleaned = cleaned.replace(/"findingId":\s*"[^"]*"/g, '"findingId":"[FINDING_ID]"');
+
+  return cleaned;
+}
+
+/**
+ * Compute SHA256 hash of content
+ */
+function hashContent(content) {
+  const hash = createHash('sha256');
+  hash.update(content, 'utf-8');
+  return hash.digest('hex');
+}
+
+/**
+ * Normalize and hash a JSON file
+ */
+function hashJSONFile(filePath, volatileFields = []) {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+    const parsed = JSON.parse(content);
+    const normalized = normalizeJSON(parsed, volatileFields);
+    const serialized = JSON.stringify(normalized);
+    const stripped = stripVolatile(serialized);
+    return hashContent(stripped);
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Hash a raw file (e.g., screenshot PNG)
+ */
+function _hashFile(filePath) {
+  try {
+    const content = readFileSync(filePath);
+    return hashContent(content.toString('utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * H5: Compute deterministic digest for observations
+ * Ensures identical inputs produce identical digests
+ * Used for reproducibility proof
+ */
+export function computeDigest(expectations, observations, metadata = {}) {
+  const digest = {
+    version: '1.0',
+    deterministicSeed: 'verax-h5-determinism-proof',
+    contentHashes: {},
+    normalized: {},
+  };
+
+  // Normalize expectations
+  const normalizedExpectations = (expectations || []).map(exp => ({
+    id: exp.id,
+    type: exp.type,
+    category: exp.category,
+    promise: exp.promise,
+  }));
+
+  const expString = JSON.stringify(normalizedExpectations);
+  digest.contentHashes.expectations = hashContent(expString);
+  digest.normalized.expectations = normalizedExpectations;
+
+  // Normalize observations (remove timing)
+  const normalizedObservations = (observations || []).map(obs => ({
+    id: obs.id,
+    category: obs.category,
+    observed: obs.observed,
+    reason: obs.reason,
+  }));
+
+  const obsString = JSON.stringify(normalizedObservations);
+  digest.contentHashes.observations = hashContent(obsString);
+  digest.normalized.observations = normalizedObservations;
+
+  // Normalize metadata
+  const normalizedMetadata = {
+    framework: metadata.framework,
+    url: metadata.url,
+    version: metadata.version,
+  };
+
+  const metaString = JSON.stringify(normalizedMetadata);
+  digest.contentHashes.metadata = hashContent(metaString);
+  digest.normalized.metadata = normalizedMetadata;
+
+  // Compute final digest
+  const digestInput = [
+    digest.contentHashes.expectations,
+    digest.contentHashes.observations,
+    digest.contentHashes.metadata,
+    digest.deterministicSeed,
+  ].join(':');
+
+  digest.deterministicDigest = hashContent(digestInput);
+
+  return digest;
+}
+
+/**
+ * H5: Validate determinism across multiple runs
+ */
+export function validateDeterminism(digests) {
+  if (!digests || digests.length === 0) {
+    return {
+      isDeterministic: true,
+      reason: 'No runs to compare',
+    };
+  }
+
+  const firstDigest = digests[0].deterministicDigest;
+  const allMatch = digests.every(d => d.deterministicDigest === firstDigest);
+
+  return {
+    isDeterministic: allMatch,
+    firstDigest,
+    mismatchedRuns: !allMatch ? digests.map((d, i) => ({
+      runIndex: i,
+      digest: d.deterministicDigest,
+    })).filter(d => d.digest !== firstDigest) : [],
+  };
+}
+
+/**
+ * Produce a complete run digest
+ */
+export async function produceRunDigest(runPath, runData) {
+  const digest = {
+    format: 'run-digest-v1',
+    timestamp: new Date().toISOString(),
+    digests: {
+      learn: null,
+      observe: null,
+      findings: null,
+      evidence: {},
+    },
+    metadata: {
+      runPath,
+      isReproducible: false,
+    },
+  };
+
+  // Hash learn.json (should be deterministic)
+  const learnPath = resolve(runPath, 'learn.json');
+  const learnHash = hashJSONFile(learnPath, ['extractedAt', 'duration']);
+  if (learnHash) {
+    digest.digests.learn = learnHash;
+  }
+
+  // Hash observe.json (normalized)
+  const observePath = resolve(runPath, 'observe.json');
+  const observeHash = hashJSONFile(observePath, [
+    'observedAt',
+    'startedAt',
+    'endedAt',
+    'timing',
+    'duration',
+    'findingId',
+  ]);
+  if (observeHash) {
+    digest.digests.observe = observeHash;
+  }
+
+  // Hash findings.json (normalized)
+  const findingsPath = resolve(runPath, 'findings.json');
+  const findingsHash = hashJSONFile(findingsPath, ['findingId', 'confidence']);
+  if (findingsHash) {
+    digest.digests.findings = findingsHash;
+  }
+
+  // Hash evidence directory
+  if (runData?.evidence && Array.isArray(runData.evidence)) {
+    const evidenceDigests = {};
+    for (const evidenceFile of runData.evidence) {
+      if (evidenceFile.endsWith('.png') || evidenceFile.endsWith('.jpg')) {
+        // Skip images (they may have subtle compression differences)
+        evidenceDigests[evidenceFile] = '[IMAGE_SKIPPED]';
+      } else if (evidenceFile.endsWith('.json')) {
+        const filePath = resolve(runPath, 'evidence', evidenceFile);
+        const hash = hashJSONFile(filePath, ['timestamp', 'duration']);
+        if (hash) {
+          evidenceDigests[evidenceFile] = hash;
+        }
+      }
+    }
+    digest.digests.evidence = evidenceDigests;
+  }
+
+  // Determine if reproducible (all core files match if run again)
+  const hasAllHashes =
+    digest.digests.learn &&
+    digest.digests.observe &&
+    digest.digests.findings &&
+    Object.keys(digest.digests.evidence).length > 0;
+
+  digest.metadata.isReproducible = hasAllHashes;
+
+  return digest;
+}
+
+/**
+ * Compare two digests for determinism
+ */
+export function compareDigests(digest1, digest2) {
+  const comparison = {
+    match: false,
+    diffs: [],
+  };
+
+  // Learn must match (deterministic)
+  if (digest1.digests.learn !== digest2.digests.learn) {
+    comparison.diffs.push('learn.json hash differs');
+  }
+
+  // Observe must match (deterministic execution)
+  if (digest1.digests.observe !== digest2.digests.observe) {
+    comparison.diffs.push('observe.json hash differs');
+  }
+
+  // Findings must match (deterministic classification)
+  if (digest1.digests.findings !== digest2.digests.findings) {
+    comparison.diffs.push('findings.json hash differs');
+  }
+
+  // Evidence files should match
+  const evidenceKeys1 = Object.keys(digest1.digests.evidence || {});
+  const evidenceKeys2 = Object.keys(digest2.digests.evidence || {});
+
+  if (evidenceKeys1.length !== evidenceKeys2.length) {
+    comparison.diffs.push(
+      `Evidence count differs: ${evidenceKeys1.length} vs ${evidenceKeys2.length}`
+    );
+  }
+
+  for (const key of evidenceKeys1) {
+    if (
+      digest1.digests.evidence[key] &&
+      digest2.digests.evidence[key] &&
+      digest1.digests.evidence[key] !== '[IMAGE_SKIPPED]' &&
+      digest1.digests.evidence[key] !== digest2.digests.evidence[key]
+    ) {
+      comparison.diffs.push(`Evidence file '${key}' hash differs`);
+    }
+  }
+
+  comparison.match = comparison.diffs.length === 0;
+
+  return comparison;
+}
+
+/**
+ * Save digest to file
+ */
+export function saveDigest(digestPath, digest) {
+  try {
+    writeFileSync(digestPath, JSON.stringify(digest, null, 2), 'utf-8');
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Load digest from file
+ */
+export function loadDigest(digestPath) {
+  try {
+    const content = readFileSync(digestPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+    return JSON.parse(content);
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Check if a run is deterministically reproducible
+ */
+export function isRunDeterministic(digest) {
+  if (!digest) return false;
+  return (
+    Boolean(digest.digests.learn) &&
+    Boolean(digest.digests.observe) &&
+    Boolean(digest.digests.findings)
+  );
+}

package/src/cli/util/dom-diff.js

@@ -0,0 +1,226 @@
+/**
+ * DOM Diff Engine
+ * Computes structured differences between HTML snapshots
+ * Distinguishes meaningful changes from noise
+ */
+
+/**
+ * Compute a diff between two HTML documents
+ * Returns a summary of changes without full tree comparison (for performance)
+ * Includes isMeaningful flag to distinguish signal from noise
+ */
+export function computeDOMDiff(htmlBefore, htmlAfter) {
+  const _before = parseHTML(htmlBefore);
+  const _after = parseHTML(htmlAfter);
+  
+  const diff = {
+    htmlLengthBefore: htmlBefore.length,
+    htmlLengthAfter: htmlAfter.length,
+    changed: htmlBefore !== htmlAfter,
+    isMeaningful: false,
+    elementsRemoved: [],
+    elementsAdded: [],
+    attributesChanged: [],
+    contentChanged: [],
+  };
+  
+  if (!diff.changed) {
+    return diff;
+  }
+  
+  // Check if this is only noise (timestamps, random ids, tracking)
+  if (isNoisyChangeOnly(htmlBefore, htmlAfter)) {
+    diff.changed = true;
+    diff.isMeaningful = false;
+    return diff;
+  }
+  
+  // Quick heuristics for specific changes
+  // Check for new elements with specific roles/classes that indicate feedback
+  const feedbackPatterns = [
+    'role="alert"',
+    'role="status"',
+    'aria-live',
+    'class="toast"',
+    'class="error"',
+    'class="success"',
+    'class="modal"',
+    'class="dialog"',
+    '[data-error]',
+    '[data-success]',
+  ];
+  
+  for (const pattern of feedbackPatterns) {
+    if (!htmlBefore.includes(pattern) && htmlAfter.includes(pattern)) {
+      diff.elementsAdded.push(pattern);
+      diff.isMeaningful = true;
+    }
+    if (htmlBefore.includes(pattern) && !htmlAfter.includes(pattern)) {
+      diff.elementsRemoved.push(pattern);
+      diff.isMeaningful = true;
+    }
+  }
+  
+  // Check for attribute changes (disabled, aria-invalid, etc.)
+  const attrPatterns = [
+    'disabled',
+    'aria-invalid',
+    'aria-disabled',
+    'data-loading',
+  ];
+  
+  for (const attr of attrPatterns) {
+    const beforeCount = countOccurrences(htmlBefore, attr);
+    const afterCount = countOccurrences(htmlAfter, attr);
+    
+    if (beforeCount !== afterCount) {
+      diff.attributesChanged.push({
+        attribute: attr,
+        before: beforeCount,
+        after: afterCount,
+      });
+      diff.isMeaningful = true;
+    }
+  }
+  
+  // Check for form state changes (values, structure)
+  if (checkFormStateChange(htmlBefore, htmlAfter)) {
+    diff.isMeaningful = true;
+  }
+  
+  return diff;
+}
+
+/**
+ * Parse HTML and return basic structure info
+ */
+function parseHTML(html) {
+  return {
+    bodyLength: html.length,
+    hasHead: html.includes('<head'),
+    hasBody: html.includes('<body'),
+    formCount: countOccurrences(html, '<form'),
+    inputCount: countOccurrences(html, '<input'),
+    buttonCount: countOccurrences(html, '<button'),
+  };
+}
+
+/**
+ * Count occurrences of a substring
+ */
+function countOccurrences(str, substr) {
+  let count = 0;
+  let pos = 0;
+  while ((pos = str.indexOf(substr, pos)) !== -1) {
+    count++;
+    pos += substr.length;
+  }
+  return count;
+}
+
+/**
+ * Detect if DOM appears to have feedback elements
+ */
+export function hasFeedbackElements(html) {
+  const feedbackIndicators = [
+    'role="alert"',
+    'role="status"',
+    'aria-live="polite"',
+    'aria-live="assertive"',
+    'toast',
+    'error',
+    'success',
+    'validation',
+  ];
+  
+  return feedbackIndicators.some(indicator => 
+    html.includes(indicator)
+  );
+}
+
+/**
+ * Detect if DOM appears to have validation errors
+ */
+export function hasValidationErrors(html) {
+  const errorPatterns = [
+    'aria-invalid="true"',
+    'aria-invalid=\'true\'',
+    'invalid',
+    'error',
+    'required',
+  ];
+  
+  return errorPatterns.some(pattern => html.includes(pattern));
+}
+
+/**
+ * Check if the HTML change is only noise (timestamps, random IDs, tracking pixels)
+ * Returns true if ONLY noise detected, false if meaningful changes exist
+ */
+function isNoisyChangeOnly(htmlBefore, htmlAfter) {
+  // Make a copy and remove known noise patterns
+  let before = htmlBefore;
+  let after = htmlAfter;
+  
+  // Remove timestamps (ISO, Unix, etc.)
+  const timestampPattern = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[^"']*/g;
+  before = before.replace(timestampPattern, '[TIMESTAMP]');
+  after = after.replace(timestampPattern, '[TIMESTAMP]');
+  
+  // Remove UUID-like patterns
+  const uuidPattern = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+  before = before.replace(uuidPattern, '[UUID]');
+  after = after.replace(uuidPattern, '[UUID]');
+  
+  // Remove random hash-like values
+  const hashPattern = /[a-f0-9]{32,}/g;
+  before = before.replace(hashPattern, '[HASH]');
+  after = after.replace(hashPattern, '[HASH]');
+  
+  // Remove tracking params (ga, fbclid, etc.)
+  const trackingPattern = /[?&](ga[a-z_]*|fbclid|utm_[a-z]*|gclid|msclkid)=[^&"']*/g;
+  before = before.replace(trackingPattern, '[TRACKING]');
+  after = after.replace(trackingPattern, '[TRACKING]');
+  
+  // Remove data-testid and similar noise attrs
+  const testIdPattern = /data-testid="[^"]*"/g;
+  before = before.replace(testIdPattern, '');
+  after = after.replace(testIdPattern, '');
+  
+  // If they're now equal, it was only noise
+  return before === after;
+}
+
+/**
+ * Check for meaningful form state changes
+ */
+function checkFormStateChange(htmlBefore, htmlAfter) {
+  // Check for form input value changes (meaningful state change)
+  const beforeInputs = extractInputValues(htmlBefore);
+  const afterInputs = extractInputValues(htmlAfter);
+  
+  if (beforeInputs.size !== afterInputs.size) {
+    return true;
+  }
+  
+  for (const [key, value] of beforeInputs) {
+    if (afterInputs.get(key) !== value) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Extract input name-value pairs from HTML
+ */
+function extractInputValues(html) {
+  const values = new Map();
+  const inputPattern = /<input[^>]*name="([^"]*)"[^>]*value="([^"]*)"/g;
+  let match;
+  while ((match = inputPattern.exec(html)) !== null) {
+    values.set(match[1], match[2]);
+  }
+  return values;
+}