@veraxhq/verax 0.1.0 → 0.2.0

package/src/verax/cli/run-overview.js

@@ -0,0 +1,163 @@
+/**
+ * Wave 6 — Run Overview
+ * 
+ * Generates a clear, human-readable overview of the scan run.
+ */
+
+/**
+ * Generate run overview data structure
+ * @param {Object} context - Scan context
+ * @returns {Object} Overview data
+ */
+export function generateRunOverview(context = {}) {
+  const {
+    manifest = null,
+    expectationsSummary = { total: 0, navigation: 0, networkActions: 0, stateActions: 0 },
+    interactionsObserved = 0,
+    contextCheck = null,
+    verdict = 'UNKNOWN',
+    findingsCount = 0
+  } = context;
+  
+  const projectType = manifest?.projectType || 'unknown';
+  const expectationsTotal = expectationsSummary.total || 0;
+  
+  // Determine validation status
+  let validationStatus = 'skipped';
+  let validationReason = 'No routes to validate';
+  
+  if (contextCheck && contextCheck.ran) {
+    if (contextCheck.verdict === 'VALID_CONTEXT') {
+      validationStatus = 'validated';
+      validationReason = `${contextCheck.matchedRoutesCount} routes matched`;
+    } else if (contextCheck.verdict === 'INVALID_CONTEXT') {
+      validationStatus = 'mismatch';
+      validationReason = 'URL does not match project';
+    } else if (contextCheck.verdict === 'INVALID_CONTEXT_FORCED') {
+      validationStatus = 'forced';
+      validationReason = 'Scan continued with --force despite mismatch';
+    }
+  }
+  
+  // Generate trust statement
+  let trustLevel = 'low';
+  const trustReasons = [];
+  
+  if (verdict === 'VERIFIED') {
+    trustLevel = 'high';
+    trustReasons.push(`All ${expectationsTotal} expectations validated`);
+    trustReasons.push(`${interactionsObserved} interactions tested`);
+    if (validationStatus === 'validated') {
+      trustReasons.push('Context validated');
+    }
+  } else if (verdict === 'ISSUES_FOUND') {
+    trustLevel = 'high';
+    trustReasons.push(`${expectationsTotal} expectations analyzed`);
+    trustReasons.push(`${interactionsObserved} interactions tested`);
+    trustReasons.push(`${findingsCount} issue(s) detected`);
+  } else if (verdict === 'NO_EXPECTATIONS_FOUND') {
+    trustLevel = 'low';
+    trustReasons.push('No code-derived expectations found');
+    trustReasons.push('Cannot validate without expectations');
+  } else if (verdict === 'INVALID_CONTEXT' || verdict === 'INVALID_CONTEXT_FORCED') {
+    trustLevel = 'partial';
+    trustReasons.push(`${expectationsTotal} expectations found`);
+    if (validationStatus === 'forced') {
+      trustReasons.push('Context mismatch (forced scan)');
+    } else {
+      trustReasons.push('Context mismatch - scan stopped early');
+    }
+    if (interactionsObserved === 0) {
+      trustReasons.push('No interactions executed');
+    }
+  }
+  
+  // Adjust trust level based on interactions
+  if (expectationsTotal > 0 && interactionsObserved === 0 && verdict !== 'INVALID_CONTEXT') {
+    trustLevel = 'partial';
+    if (!trustReasons.some(r => r.includes('No interactions'))) {
+      trustReasons.push('No interactions executed - validation incomplete');
+    }
+  }
+  
+  // Explicitly mention skipped expectations
+  if (context?.expectationsUnused !== undefined && context.expectationsUnused > 0) {
+    if (trustLevel === 'high') {
+      trustLevel = 'partial';
+    }
+    trustReasons.push(`${context.expectationsUnused} expectation(s) unused - partial validation`);
+  }
+  
+  return {
+    projectType: projectType,
+    expectationsFound: expectationsTotal,
+    expectationsByType: {
+      navigation: expectationsSummary.navigation || 0,
+      networkActions: expectationsSummary.networkActions || 0,
+      stateActions: expectationsSummary.stateActions || 0
+    },
+    interactionsExecuted: interactionsObserved,
+    validationStatus: validationStatus,
+    validationReason: validationReason,
+    trustLevel: trustLevel,
+    trustReasons: trustReasons
+  };
+}
+
+/**
+ * Print run overview console block
+ * @param {Object} overview - Overview data from generateRunOverview
+ * @param {boolean} isCI - Whether in CI mode
+ */
+export function printRunOverview(overview, isCI = false) {
+  if (isCI) {
+    // Compact CI format
+    console.error(`VERAX Run: ${overview.projectType} | ${overview.expectationsFound} expectations | ${overview.interactionsExecuted} interactions | ${overview.validationStatus}`);
+    return;
+  }
+  
+  // Full format
+  console.error('\n' + '═'.repeat(60));
+  console.error('Run Overview');
+  console.error('═'.repeat(60));
+  
+  console.error(`Project Type: ${overview.projectType}`);
+  
+  console.error(`\nExpectations Found: ${overview.expectationsFound}`);
+  if (overview.expectationsFound > 0) {
+    const types = [];
+    if (overview.expectationsByType.navigation > 0) {
+      types.push(`navigation (${overview.expectationsByType.navigation})`);
+    }
+    if (overview.expectationsByType.networkActions > 0) {
+      types.push(`network actions (${overview.expectationsByType.networkActions})`);
+    }
+    if (overview.expectationsByType.stateActions > 0) {
+      types.push(`state actions (${overview.expectationsByType.stateActions})`);
+    }
+    if (types.length > 0) {
+      console.error(`  Types: ${types.join(', ')}`);
+    }
+  }
+  
+  console.error(`\nInteractions Executed: ${overview.interactionsExecuted}`);
+  
+  console.error(`\nValidation Status: ${overview.validationStatus}`);
+  console.error(`  ${overview.validationReason}`);
+  
+  // Trust statement
+  console.error(`\nTrust Assessment: ${overview.trustLevel.toUpperCase()}`);
+  const trustPrefix = overview.trustLevel === 'high' 
+    ? 'This result is trustworthy because'
+    : overview.trustLevel === 'partial'
+    ? 'This result is limited because'
+    : 'This result cannot be trusted because';
+  
+  console.error(`  ${trustPrefix}:`);
+  overview.trustReasons.forEach(reason => {
+    console.error(`  • ${reason}`);
+  });
+  
+  console.error('═'.repeat(60) + '\n');
+}
+

package/src/verax/cli/url-safety.js

@@ -0,0 +1,101 @@
+/**
+ * Wave 3 — URL Safety Checks
+ * 
+ * Detects external/public URLs and requires confirmation.
+ */
+
+/**
+ * Check if an IP address is private/local
+ * @param {string} ip - IP address
+ * @returns {boolean} True if private/local
+ */
+function isPrivateIP(ip) {
+  // localhost
+  if (ip === '127.0.0.1' || ip === '::1' || ip === 'localhost') {
+    return true;
+  }
+  
+  // Private IP ranges
+  const privateRanges = [
+    /^10\./,                    // 10.0.0.0/8
+    /^172\.(1[6-9]|2[0-9]|3[01])\./, // 172.16.0.0/12
+    /^192\.168\./,              // 192.168.0.0/16
+    /^169\.254\./,              // Link-local
+    /^fc00:/,                   // IPv6 private
+    /^fe80:/                    // IPv6 link-local
+  ];
+  
+  return privateRanges.some(range => range.test(ip));
+}
+
+/**
+ * Check if URL is external/public (requires confirmation)
+ * @param {string} url - URL to check
+ * @returns {Object} { isExternal: boolean, hostname: string }
+ */
+export function checkUrlSafety(url) {
+  try {
+    const urlObj = new URL(url);
+    const hostname = urlObj.hostname;
+    
+    // Check if localhost
+    if (hostname === 'localhost' || hostname === '127.0.0.1') {
+      return {
+        isExternal: false,
+        hostname: hostname
+      };
+    }
+    
+    // Check if private IP
+    if (isPrivateIP(hostname)) {
+      return {
+        isExternal: false,
+        hostname: hostname
+      };
+    }
+    
+    // All other hosts are considered external
+    return {
+      isExternal: true,
+      hostname: hostname
+    };
+  } catch (error) {
+    // Invalid URL - let other validation catch it
+    return {
+      isExternal: false,
+      hostname: null
+    };
+  }
+}
+
+/**
+ * Prompt for external URL confirmation
+ * @param {string} hostname - Hostname to confirm
+ * @param {Object} options - Options
+ * @param {Function} options.readlineInterface - Readline interface (injectable)
+ * @returns {Promise<boolean>} True if confirmed
+ */
+export async function confirmExternalUrl(hostname, options = {}) {
+  const rl = options.readlineInterface || null;
+  
+  if (!rl) {
+    // Use readline if not injected
+    const readline = await import('readline/promises');
+    const rlInterface = readline.default.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true
+    });
+    
+    try {
+      const answer = await rlInterface.question(`This will scan a public site (${hostname}). Continue? (y/N): `);
+      return (answer.trim().toLowerCase() || 'n').startsWith('y');
+    } finally {
+      rlInterface.close();
+    }
+  } else {
+    const answer = await rl.question(`This will scan a public site (${hostname}). Continue? (y/N): `);
+    return (answer.trim().toLowerCase() || 'n').startsWith('y');
+  }
+}
+

package/src/verax/cli/wizard.js

@@ -0,0 +1,98 @@
+/**
+ * Wave 3 — Interactive Wizard
+ * 
+ * Guides users through VERAX configuration with friendly prompts.
+ */
+
+/**
+ * Create a readline interface (can be injected for testing)
+ */
+async function createReadlineInterface(input = process.stdin, output = process.stdout) {
+  const readline = await import('readline/promises');
+  return readline.default.createInterface({
+    input,
+    output,
+    terminal: true
+  });
+}
+
+/**
+ * Run interactive wizard
+ * @param {Object} options - Options for wizard
+ * @param {Function} options.readlineInterface - Readline interface (injectable for testing)
+ * @returns {Promise<Object>} Wizard results
+ */
+export async function runWizard(options = {}) {
+  const rl = options.readlineInterface || await createReadlineInterface();
+  
+  try {
+    console.log('VERAX — Silent Failure Detection\n');
+    console.log('This wizard will guide you through setting up a VERAX scan.\n');
+    
+    // 1. Mode selection (Wave 7: add init and doctor)
+    const modeAnswer = await rl.question('Mode: (s)can, (f)low, (i)nit, or (d)octor? [s]: ');
+    const modeInput = (modeAnswer.trim().toLowerCase() || 's');
+    let mode;
+    if (modeInput.startsWith('i')) {
+      mode = 'init';
+    } else if (modeInput.startsWith('d')) {
+      mode = 'doctor';
+    } else if (modeInput.startsWith('f')) {
+      mode = 'flow';
+    } else {
+      mode = 'scan';
+    }
+    
+    // For init and doctor modes, return early
+    if (mode === 'init' || mode === 'doctor') {
+      return { mode };
+    }
+    
+    // 2. URL
+    const urlAnswer = await rl.question('URL to scan [http://localhost:3000]: ');
+    let url = urlAnswer.trim();
+    if (!url) {
+      url = 'http://localhost:3000';
+    }
+    if (!url.startsWith('http://') && !url.startsWith('https://')) {
+      url = 'http://' + url;
+    }
+    
+    // 3. Project root (for scan) or flow file (for flow)
+    let projectRoot = process.cwd();
+    let flowPath = null;
+    
+    if (mode === 'scan') {
+      const projectRootAnswer = await rl.question(`Project root [${projectRoot}]: `);
+      if (projectRootAnswer.trim()) {
+        projectRoot = projectRootAnswer.trim();
+      }
+    } else {
+      const flowPathAnswer = await rl.question('Flow file path: ');
+      flowPath = flowPathAnswer.trim();
+      if (!flowPath) {
+        throw new Error('Flow file path is required');
+      }
+    }
+    
+    // 4. JSON output
+    const jsonAnswer = await rl.question('JSON output? (y/N) [N]: ');
+    const jsonOutput = (jsonAnswer.trim().toLowerCase() || 'n').startsWith('y');
+    
+    // 5. Output directory
+    const outDirAnswer = await rl.question(`Output directory [.verax/runs]: `);
+    const outDir = outDirAnswer.trim() || '.verax/runs';
+    
+    return {
+      mode,
+      url,
+      projectRoot,
+      flowPath,
+      json: jsonOutput,
+      out: outDir
+    };
+  } finally {
+    rl.close();
+  }
+}
+

package/src/verax/cli/zero-findings-explainer.js

@@ -0,0 +1,57 @@
+/**
+ * Zero Findings Explanation
+ * 
+ * Observational explanation of zero findings (not a judgment).
+ */
+
+/**
+ * Generate explanation for zero findings
+ * @param {Object} context - Context information
+ * @returns {Array<string>} Explanation lines
+ */
+export function explainZeroFindings(context = {}) {
+  const {
+    expectationsCount = 0,
+    interactionsObserved = 0,
+    discrepanciesObserved = 0
+  } = context;
+  
+  const lines = [
+    '────────────────────────────────────────────────────────────',
+    'OBSERVATION: No Discrepancies Detected',
+    '────────────────────────────────────────────────────────────',
+    '',
+    `VERAX analyzed ${expectationsCount} code-derived expectations`,
+    `Observed ${interactionsObserved} user interactions`,
+    `Discrepancies observed: ${discrepanciesObserved}`,
+    '',
+    'What this means:',
+    '  • During this scan, no discrepancies were observed between code promises and runtime behavior',
+    '  • This does NOT guarantee safety, correctness, or completeness',
+    '  • Some expectations may not have been evaluated (see gaps below)',
+    '',
+    'What was not observed:',
+  ];
+  
+  if (expectationsCount === 0) {
+    lines.push('  • No expectations found in code - no evaluation was possible');
+    lines.push('  • VERAX requires PROVEN expectations (static patterns) to observe behavior');
+  } else {
+    lines.push('  • Check coverage gaps to see what was not evaluated');
+  }
+  
+  return lines;
+}
+
+/**
+ * Print zero findings explanation
+ * @param {Object} context - Context
+ */
+export function printZeroFindingsExplanation(context = {}) {
+  const lines = explainZeroFindings(context);
+  lines.forEach(line => {
+    console.error(line);
+  });
+  console.error('');
+}
+

package/src/verax/cli/zero-interaction-explainer.js

@@ -0,0 +1,127 @@
+/**
+ * Wave 6 — Zero Interaction Explanation
+ * 
+ * Explains why no interactions were executed and what could/could not be validated.
+ */
+
+/**
+ * Explain why no interactions were executed
+ * @param {Object} context - Scan context
+ * @returns {Array<string>} Explanation lines
+ */
+export function explainZeroInteractions(context = {}) {
+  const {
+    verdict = 'UNKNOWN',
+    contextCheck = null,
+    interactionsObserved = 0,
+    expectationsTotal = 0,
+    observation = null
+  } = context;
+  
+  // If interactions were actually observed, return empty
+  if (interactionsObserved > 0) {
+    return [];
+  }
+  
+  // If no expectations, different explanation
+  if (expectationsTotal === 0) {
+    return [
+      'No interactions executed because no expectations were found.',
+      'VERAX needs code-derived expectations to know what to test.'
+    ];
+  }
+  
+  const reasons = [];
+  
+  // Context validation stopped early
+  if (verdict === 'INVALID_CONTEXT' && contextCheck && !contextCheck.forced) {
+    reasons.push([
+      '⚠️  No interactions executed because context validation failed.',
+      '',
+      'VERAX stopped the scan early to prevent analyzing the wrong site.',
+      '',
+      'What VERAX could validate:',
+      `  ✓ Discovered ${expectationsTotal} expectations from your code`,
+      '  ✗ Could not validate interactions (scan stopped)',
+      '',
+      'What to do:',
+      '  • Use --force to scan anyway, or',
+      '  • Ensure your URL matches the project being analyzed'
+    ]);
+  } else if (verdict === 'INVALID_CONTEXT_FORCED') {
+    reasons.push([
+      '⚠️  Limited interactions executed due to context mismatch.',
+      '',
+      'VERAX continued with --force but may not have found expected routes.',
+      '',
+      'What VERAX validated:',
+      `  ✓ ${expectationsTotal} expectations found`,
+      '  ⚠ Interactions may not match expectations (context mismatch)',
+      '',
+      'What to do:',
+      '  • Verify URL matches project deployment',
+      '  • Check that routes exist on the live site'
+    ]);
+  } else {
+    // No interactions discovered or executed
+    const observationDetails = observation?.observeTruth || {};
+    
+    if (observationDetails.interactionsObserved === 0) {
+      reasons.push([
+        '⚠️  No interactions executed.',
+        '',
+        'VERAX could not discover any interactive elements on the page.',
+        '',
+        'What VERAX could validate:',
+        `  ✓ Discovered ${expectationsTotal} expectations from your code`,
+        '  ✗ Could not test interactions (no discoverable elements)',
+        '',
+        'Possible reasons:',
+        '  • Page has no clickable links, buttons, or forms',
+        '  • Elements are hidden or not rendered',
+        '  • JavaScript errors prevented interaction discovery',
+        '',
+        'What to do:',
+        '  • Verify the page loads correctly',
+        '  • Check browser console for errors',
+        '  • Ensure interactive elements are visible and accessible'
+      ]);
+    } else {
+      // Interactions discovered but none executed
+      reasons.push([
+        '⚠️  No interactions executed despite discoveries.',
+        '',
+        'VERAX discovered interactions but could not execute them.',
+        '',
+        'What VERAX could validate:',
+        `  ✓ Discovered ${expectationsTotal} expectations from your code`,
+        '  ✗ Could not test interactions (execution failed)',
+        '',
+        'What to do:',
+        '  • Check network connectivity',
+        '  • Verify page is accessible',
+        '  • Review error logs for details'
+      ]);
+    }
+  }
+  
+  return reasons.flat();
+}
+
+/**
+ * Print zero interaction explanation
+ * @param {Object} context - Scan context
+ */
+export function printZeroInteractionExplanation(context) {
+  const explanation = explainZeroInteractions(context);
+  if (explanation.length > 0) {
+    console.error('\n' + '─'.repeat(60));
+    console.error('Interaction Status');
+    console.error('─'.repeat(60));
+    explanation.forEach(line => {
+      console.error(line);
+    });
+    console.error('─'.repeat(60) + '\n');
+  }
+}
+

package/src/verax/core/action-classifier.js

@@ -0,0 +1,86 @@
+/**
+ * ACTION CLASSIFIER
+ * 
+ * Classifies user interactions by safety level for misuse resistance.
+ * NO JUDGMENT SEMANTICS - only risk classification for protection.
+ * 
+ * Classifications:
+ * - SAFE_READONLY: Navigation, focus, hover, non-submitting clicks
+ * - RISKY: Destructive actions (delete/remove/clear data), logout, admin
+ * - WRITE_INTENT: State-changing actions (submit, file upload, checkout/pay)
+ * 
+ * Phase 4: Default safe mode blocks RISKY and WRITE_INTENT unless explicitly allowed.
+ */
+
+/**
+ * Classify an interaction's safety level
+ * @param {Object} interaction - Interaction object with type, text, label, selector
+ * @returns {Object} { classification: string, reason: string }
+ */
+export function classifyAction(interaction) {
+  const type = (interaction.type || '').toLowerCase();
+  const text = (interaction.text || '').toLowerCase().trim();
+  const label = (interaction.label || '').toLowerCase().trim();
+  const ariaLabel = (interaction.ariaLabel || '').toLowerCase().trim();
+  const selector = (interaction.selector || '').toLowerCase();
+  const combined = `${text} ${label} ${ariaLabel}`.trim();
+
+  // RISKY patterns - destructive/dangerous actions
+  const riskyKeywords = /\b(delete|remove|erase|wipe|destroy|drop|clear\s+(data|all|history|cache|account|database|storage)|reset\s+(account|data|database)|deactivate|terminate|uninstall|unsubscribe)\b/i;
+  const adminKeywords = /\b(admin|administrator|sudo|root|settings|config|preferences)\b/i;
+  
+  if (riskyKeywords.test(combined)) {
+    return { classification: 'RISKY', reason: 'destructive_keyword' };
+  }
+
+  // Logout/signout treated as risky (state loss)
+  if (/\b(logout|sign\s*out|log\s*out)\b/i.test(combined)) {
+    return { classification: 'RISKY', reason: 'auth_logout' };
+  }
+
+  // Admin/config actions risky
+  if (adminKeywords.test(combined) && !/view|read|show/.test(combined)) {
+    return { classification: 'RISKY', reason: 'admin_action' };
+  }
+
+  // WRITE_INTENT patterns - state-changing actions
+  const writeKeywords = /\b(submit|send|post|save|update|create|add|checkout|purchase|pay|buy|order|upload|attach|edit|modify)\b/i;
+  
+  if (writeKeywords.test(combined)) {
+    return { classification: 'WRITE_INTENT', reason: 'write_keyword' };
+  }
+
+  // Form submissions are write intent
+  if (type === 'submit' || selector.includes('type="submit"') || selector.includes('[type=submit]')) {
+    return { classification: 'WRITE_INTENT', reason: 'form_submit' };
+  }
+
+  // File inputs are write intent
+  if (type === 'file' || selector.includes('type="file"') || selector.includes('input[type=file]')) {
+    return { classification: 'WRITE_INTENT', reason: 'file_input' };
+  }
+
+  // Default: safe readonly (navigation, clicks, focus, hover)
+  return { classification: 'SAFE_READONLY', reason: 'default_safe' };
+}
+
+/**
+ * Check if action should be blocked based on safety mode and flags
+ * @param {Object} interaction - Interaction to check
+ * @param {Object} flags - Safety flags { allowWrites: boolean, allowRiskyActions: boolean }
+ * @returns {Object} { shouldBlock: boolean, classification: string, reason: string }
+ */
+export function shouldBlockAction(interaction, flags = {}) {
+  const { allowWrites = false, allowRiskyActions = false } = flags;
+  const { classification, reason } = classifyAction(interaction);
+
+  if (classification === 'RISKY' && !allowRiskyActions) {
+    return { shouldBlock: true, classification, reason };
+  }
+
+  if (classification === 'WRITE_INTENT' && !allowWrites) {
+    return { shouldBlock: true, classification, reason };
+  }
+
+  return { shouldBlock: false, classification, reason };
+}