@veraxhq/verax 0.3.0 → 0.4.0

package/src/verax/core/integrity/determinism.js

@@ -0,0 +1,342 @@
+/**
+ * PHASE 6A: Semantic Determinism Comparison
+ * 
+ * Provides deep semantic comparison of runs with field normalization.
+ * Ignores non-deterministic fields (timestamps, IDs, paths).
+ */
+
+import { readFileSync } from 'fs';
+import { join, normalize } from 'path';
+import { createHash } from 'crypto';
+
+/**
+ * Normalize non-deterministic fields for comparison
+ * 
+ * @param {any} obj - Object to normalize
+ * @param {string} basePath - Base path for path normalization
+ * @returns {any} Normalized object
+ */
+function normalizeObject(obj, basePath = '') {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+  
+  if (Array.isArray(obj)) {
+    return obj.map(item => normalizeObject(item, basePath));
+  }
+  
+  if (typeof obj !== 'object') {
+    return obj;
+  }
+  
+  const normalized = {};
+  const sortedKeys = Object.keys(obj).sort();
+  
+  for (const key of sortedKeys) {
+    const value = obj[key];
+    
+    // Skip non-deterministic fields
+    if (isNonDeterministicField(key)) {
+      continue;
+    }
+    
+    // Normalize paths
+    if (isPathField(key) && typeof value === 'string') {
+      normalized[key] = normalizePath(value, basePath);
+      continue;
+    }
+    
+    // Recursively normalize
+    normalized[key] = normalizeObject(value, basePath);
+  }
+  
+  return normalized;
+}
+
+/**
+ * Check if field name indicates non-deterministic data
+ * 
+ * @param {string} fieldName - Field name
+ * @returns {boolean} True if non-deterministic
+ */
+function isNonDeterministicField(fieldName) {
+  const nonDeterministicFields = [
+    'timestamp',
+    'createdAt',
+    'updatedAt',
+    'startedAt',
+    'completedAt',
+    'observedAt',
+    'detectedAt',
+    'generatedAt',
+    'verifiedAt',
+    'writtenAt',
+    'learnedAt',
+    'failedAt',
+    'runId',
+    'pid',
+    'duration',
+    'durationMs',
+    'totalMs',
+    'learnMs',
+    'observeMs',
+    'detectMs',
+    'relativeTime',
+    'sequence',
+  ];
+  
+  return nonDeterministicFields.includes(fieldName) ||
+         fieldName.endsWith('At') ||
+         fieldName.endsWith('Time') ||
+         fieldName.endsWith('Ms') ||
+         fieldName.includes('timestamp') ||
+         fieldName.includes('Timestamp');
+}
+
+/**
+ * Check if field name indicates path data
+ * 
+ * @param {string} fieldName - Field name
+ * @returns {boolean} True if path field
+ */
+function isPathField(fieldName) {
+  return fieldName.endsWith('Path') ||
+         fieldName.endsWith('Dir') ||
+         fieldName === 'cwd' ||
+         fieldName === 'src';
+}
+
+/**
+ * Normalize path for comparison (make relative to base)
+ * 
+ * @param {string} path - Path to normalize
+ * @param {string} basePath - Base path
+ * @returns {string} Normalized path
+ */
+function normalizePath(path, basePath) {
+  if (!path || !basePath) {
+    return path;
+  }
+  
+  // Normalize separators
+  const normalizedPath = normalize(path).replace(/\\/g, '/');
+  const normalizedBase = normalize(basePath).replace(/\\/g, '/');
+  
+  // Make relative if starts with base
+  if (normalizedPath.startsWith(normalizedBase)) {
+    return normalizedPath.substring(normalizedBase.length).replace(/^\//, '');
+  }
+  
+  return normalizedPath;
+}
+
+/**
+ * Compute semantic hash of normalized object
+ * 
+ * @param {Object} obj - Object to hash
+ * @returns {string} Semantic hash
+ */
+function computeSemanticHash(obj) {
+  // Use JSON.stringify with replacer that sorts all object keys recursively
+  const sortedReplacer = (key, value) => {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce((sorted, key) => {
+        sorted[key] = value[key];
+        return sorted;
+      }, {});
+    }
+    return value;
+  };
+  
+  const normalized = JSON.stringify(obj, sortedReplacer);
+  // @ts-expect-error - digest returns string
+  return createHash('sha256').update(normalized).digest('hex');
+}
+
+/**
+ * Compare two run summaries semantically
+ * 
+ * @param {Object} summary1 - First run summary
+ * @param {Object} summary2 - Second run summary
+ * @param {string} basePath - Base path for normalization
+ * @returns {{ identical: boolean, differences: Object[] }} Comparison result
+ */
+export function compareRunsSemantically(summary1, summary2, basePath = '') {
+  const norm1 = normalizeObject(summary1, basePath);
+  const norm2 = normalizeObject(summary2, basePath);
+  
+  const hash1 = computeSemanticHash(norm1);
+  const hash2 = computeSemanticHash(norm2);
+  
+  if (hash1 === hash2) {
+    return { identical: true, differences: [] };
+  }
+  
+  // Find differences
+  const differences = findDifferences(norm1, norm2, '');
+  
+  return { identical: false, differences };
+}
+
+/**
+ * Find differences between two normalized objects
+ * 
+ * @param {any} obj1 - First object
+ * @param {any} obj2 - Second object
+ * @param {string} path - Current path in object tree
+ * @returns {Object[]} List of differences
+ */
+function findDifferences(obj1, obj2, path) {
+  const differences = [];
+  
+  if (typeof obj1 !== typeof obj2) {
+    differences.push({
+      path,
+      type: 'type-mismatch',
+      value1: typeof obj1,
+      value2: typeof obj2,
+    });
+    return differences;
+  }
+  
+  if (obj1 === null || obj2 === null) {
+    if (obj1 !== obj2) {
+      differences.push({
+        path,
+        type: 'null-mismatch',
+        value1: obj1,
+        value2: obj2,
+      });
+    }
+    return differences;
+  }
+  
+  if (typeof obj1 !== 'object') {
+    if (obj1 !== obj2) {
+      differences.push({
+        path,
+        type: 'value-mismatch',
+        value1: obj1,
+        value2: obj2,
+      });
+    }
+    return differences;
+  }
+  
+  if (Array.isArray(obj1) !== Array.isArray(obj2)) {
+    differences.push({
+      path,
+      type: 'array-mismatch',
+      value1: Array.isArray(obj1),
+      value2: Array.isArray(obj2),
+    });
+    return differences;
+  }
+  
+  if (Array.isArray(obj1)) {
+    if (obj1.length !== obj2.length) {
+      differences.push({
+        path,
+        type: 'length-mismatch',
+        value1: obj1.length,
+        value2: obj2.length,
+      });
+    }
+    
+    const maxLen = Math.max(obj1.length, obj2.length);
+    for (let i = 0; i < maxLen; i++) {
+      differences.push(...findDifferences(
+        obj1[i],
+        obj2[i],
+        `${path}[${i}]`
+      ));
+    }
+    
+    return differences;
+  }
+  
+  // Object comparison
+  const keys1 = Object.keys(obj1).sort();
+  const keys2 = Object.keys(obj2).sort();
+  
+  const allKeys = new Set([...keys1, ...keys2]);
+  
+  for (const key of allKeys) {
+    const subPath = path ? `${path}.${key}` : key;
+    
+    if (!(key in obj1)) {
+      differences.push({
+        path: subPath,
+        type: 'missing-in-first',
+        value2: obj2[key],
+      });
+      continue;
+    }
+    
+    if (!(key in obj2)) {
+      differences.push({
+        path: subPath,
+        type: 'missing-in-second',
+        value1: obj1[key],
+      });
+      continue;
+    }
+    
+    differences.push(...findDifferences(obj1[key], obj2[key], subPath));
+  }
+  
+  return differences;
+}
+
+/**
+ * Load and compare two runs
+ * 
+ * @param {string} runDir1 - First run directory
+ * @param {string} runDir2 - Second run directory
+ * @param {string} basePath - Base path for normalization
+ * @returns {{ ok: boolean, identical?: boolean, differences?: Object[], error?: string }} Result
+ */
+export function loadAndCompareRuns(runDir1, runDir2, basePath) {
+  try {
+    const summary1Path = join(runDir1, 'summary.json');
+    const summary2Path = join(runDir2, 'summary.json');
+    
+    const content1 = readFileSync(summary1Path, 'utf8');
+    const content2 = readFileSync(summary2Path, 'utf8');
+    
+  // @ts-expect-error - readFileSync with encoding returns string
+    const summary1 = JSON.parse(content1);
+  // @ts-expect-error - readFileSync with encoding returns string
+    const summary2 = JSON.parse(content2);
+    
+    const comparison = compareRunsSemantically(summary1, summary2, basePath);
+    
+    return {
+      ok: true,
+      identical: comparison.identical,
+      differences: comparison.differences,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Normalize findings for semantic comparison
+ * 
+ * @param {Object[]} findings - Findings array
+ * @returns {Object[]} Normalized findings
+ */
+export function normalizeFindingsForComparison(findings) {
+  return findings
+    .map(f => normalizeObject(f, ''))
+    .sort((a, b) => {
+      // Sort by expectationId for stable comparison
+      const idA = a.expectationId || '';
+      const idB = b.expectationId || '';
+      return idA.localeCompare(idB);
+    });
+}

package/src/verax/core/integrity/integrity.js

@@ -0,0 +1,208 @@
+/**
+ * PHASE 6A: Cryptographic Integrity System
+ * 
+ * Provides SHA256-based integrity verification for all run artifacts.
+ * Ensures tamper detection and corruption protection.
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync, statSync as _statSync, readdirSync } from 'fs';
+import { join, basename as _basename } from 'path';
+import { atomicWriteJson } from '../../../cli/util/atomic-write.js';
+
+/**
+ * Compute SHA256 hash of file contents
+ * 
+ * @param {string} filePath - Absolute path to file
+ * @returns {{ hash: string, size: number, error?: string }} Hash result
+ */
+export function computeFileIntegrity(filePath) {
+  try {
+    const content = readFileSync(filePath);
+    const hash = createHash('sha256').update(content).digest('hex');
+    const size = content.length;
+    // @ts-expect-error - digest returns string
+    return { hash, size };
+  } catch (error) {
+    return { hash: null, size: 0, error: error.message };
+  }
+}
+
+/**
+ * Generate integrity manifest for all artifacts in run directory
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {string[]} artifactNames - List of artifact filenames to include
+ * @returns {{ manifest: Object, errors: string[] }} Manifest and any errors
+ */
+export function generateIntegrityManifest(runDir, artifactNames) {
+  const manifest = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    runDir,
+    artifacts: {},
+  };
+  
+  const errors = [];
+  
+  for (const name of artifactNames) {
+    const filePath = join(runDir, name);
+    const integrity = computeFileIntegrity(filePath);
+    
+    if (integrity.error) {
+      errors.push(`Failed to hash ${name}: ${integrity.error}`);
+      continue;
+    }
+    
+    manifest.artifacts[name] = {
+      sha256: integrity.hash,
+      size: integrity.size,
+      verifiedAt: null, // Set when verified
+    };
+  }
+  
+  return { manifest, errors };
+}
+
+/**
+ * Write integrity manifest to run directory
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {Object} manifest - Integrity manifest object
+ * @returns {{ ok: boolean, path?: string, error?: Error }} Write result
+ */
+export function writeIntegrityManifest(runDir, manifest) {
+  const manifestPath = join(runDir, 'integrity.manifest.json');
+  
+  try {
+    atomicWriteJson(manifestPath, manifest);
+    return { ok: true, path: manifestPath };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Verify artifact integrity against manifest
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {string} artifactName - Artifact filename
+ * @param {Object} manifest - Integrity manifest
+ * @returns {{ ok: boolean, error?: string, expectedHash?: string, actualHash?: string }} Verification result
+ */
+export function verifyArtifactIntegrity(runDir, artifactName, manifest) {
+  const artifactPath = join(runDir, artifactName);
+  
+  // Check if artifact exists in manifest
+  if (!manifest.artifacts[artifactName]) {
+    return {
+      ok: false,
+      error: `Artifact ${artifactName} not found in integrity manifest`,
+    };
+  }
+  
+  const expected = manifest.artifacts[artifactName];
+  const integrity = computeFileIntegrity(artifactPath);
+  
+  if (integrity.error) {
+    return {
+      ok: false,
+      error: `Failed to read artifact ${artifactName}: ${integrity.error}`,
+    };
+  }
+  
+  if (integrity.hash !== expected.sha256) {
+    return {
+      ok: false,
+      error: `Integrity violation: ${artifactName} hash mismatch`,
+      expectedHash: expected.sha256,
+      actualHash: integrity.hash,
+    };
+  }
+  
+  if (integrity.size !== expected.size) {
+    return {
+      ok: false,
+      error: `Integrity violation: ${artifactName} size mismatch (expected ${expected.size}, got ${integrity.size})`,
+    };
+  }
+  
+  return { ok: true };
+}
+
+/**
+ * Load and verify integrity manifest
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {{ ok: boolean, manifest?: Object, error?: string }} Load result
+ */
+export function loadIntegrityManifest(runDir) {
+  try {
+    const manifestPath = join(runDir, 'integrity.manifest.json');
+    const content = readFileSync(manifestPath, 'utf8');
+  // @ts-expect-error - readFileSync with encoding returns string
+    const manifest = JSON.parse(content);
+    
+    if (!manifest.version || !manifest.artifacts) {
+      return {
+        ok: false,
+        error: 'Invalid integrity manifest format',
+      };
+    }
+    
+    return { ok: true, manifest };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Failed to load integrity manifest: ${error.message}`,
+    };
+  }
+}
+
+/**
+ * Verify all artifacts in manifest
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {Object} manifest - Integrity manifest
+ * @returns {{ ok: boolean, verified: string[], failed: Array<{name: string, error: string}> }} Verification results
+ */
+export function verifyAllArtifacts(runDir, manifest) {
+  const verified = [];
+  const failed = [];
+  
+  for (const artifactName of Object.keys(manifest.artifacts)) {
+    const result = verifyArtifactIntegrity(runDir, artifactName, manifest);
+    
+    if (result.ok) {
+      verified.push(artifactName);
+    } else {
+      failed.push({
+        name: artifactName,
+        error: result.error,
+        expectedHash: result.expectedHash,
+        actualHash: result.actualHash,
+      });
+    }
+  }
+  
+  return {
+    ok: failed.length === 0,
+    verified,
+    failed,
+  };
+}
+
+/**
+ * Discover all JSON artifacts in run directory
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {string[]} List of artifact filenames
+ */
+export function discoverArtifacts(runDir) {
+  try {
+    const files = readdirSync(runDir);
+    return files.filter(f => f.endsWith('.json') && f !== 'integrity.manifest.json');
+  } catch (error) {
+    return [];
+  }
+}

package/src/verax/core/integrity/poisoning.js

@@ -0,0 +1,108 @@
+/**
+ * PHASE 6A: Run Poisoning System
+ * 
+ * Prevents consumption of incomplete or failed runs.
+ * Implements .INCOMPLETE marker for run safety.
+ */
+
+import { writeFileSync, readFileSync, unlinkSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Create poisoning marker for run
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {string} runId - Run identifier
+ * @returns {{ ok: boolean, path?: string, error?: Error }} Result
+ */
+export function createPoisonMarker(runDir, runId) {
+  try {
+    const markerPath = join(runDir, '.INCOMPLETE');
+    const marker = {
+      runId,
+      createdAt: new Date().toISOString(),
+      pid: process.pid,
+      reason: 'Run in progress',
+    };
+    
+    writeFileSync(markerPath, JSON.stringify(marker, null, 2), 'utf8');
+    
+    return { ok: true, path: markerPath };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Remove poisoning marker (only on successful completion)
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {{ ok: boolean, error?: Error }} Result
+ */
+export function removePoisonMarker(runDir) {
+  try {
+    const markerPath = join(runDir, '.INCOMPLETE');
+    
+    if (existsSync(markerPath)) {
+      unlinkSync(markerPath);
+    }
+    
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Check if run is poisoned (incomplete)
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {{ poisoned: boolean, marker?: Object, reason?: string }} Poisoning status
+ */
+export function checkPoisonMarker(runDir) {
+  try {
+    const markerPath = join(runDir, '.INCOMPLETE');
+    
+    if (!existsSync(markerPath)) {
+      return { poisoned: false };
+    }
+    
+    const content = readFileSync(markerPath, 'utf8');
+  // @ts-expect-error - readFileSync with encoding returns string
+    const marker = JSON.parse(content);
+    
+    return {
+      poisoned: true,
+      marker,
+      reason: marker.reason || 'Run incomplete',
+    };
+  } catch (error) {
+    // If marker exists but is unreadable, consider it poisoned
+    const markerPath = join(runDir, '.INCOMPLETE');
+    if (existsSync(markerPath)) {
+      return {
+        poisoned: true,
+        reason: 'Marker unreadable or corrupted',
+      };
+    }
+    
+    return { poisoned: false };
+  }
+}
+
+/**
+ * Enforce poisoning check - throw if run is poisoned
+ * 
+ * @param {string} runDir - Run directory path
+ * @throws {Error} If run is poisoned
+ */
+export function enforcePoisonCheck(runDir) {
+  const status = checkPoisonMarker(runDir);
+  
+  if (status.poisoned) {
+    throw new Error(
+      `Cannot read run: RUN_POISONED (${status.reason || 'incomplete'}). ` +
+      `Run directory: ${runDir}`
+    );
+  }
+}