@veraxhq/verax 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 VERAX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+🛡️ VERAX
+
+VERAX detects silent user failures by comparing what your code promises with what users actually experience.
+
+Silent failures don’t crash your site.
+They don’t show errors.
+They simply lose users quietly.
+
+VERAX exists to surface those failures — with evidence, not guesses.
+
+🤔 What is VERAX?
+
+A silent user failure happens when your code clearly implies that something should happen —
+but from the user’s point of view, nothing meaningful does.
+
+Examples:
+
+A button click that should navigate… but doesn’t.
+
+A form submission that triggers an API call… but shows no feedback.
+
+A state update that runs in code… but never reaches the UI.
+
+These issues are frustrating for users and difficult for teams to catch.
+
+VERAX reads your source code to understand what should happen, then opens your website in a real browser and experiences it like a human user.
+When code expectations and user reality don’t match, VERAX reports the gap — clearly and honestly.
+
+VERAX does not guess intent.
+It only reports failures that your code explicitly promises.
+
+✅ What VERAX does (today)
+
+🔍 Detects silent user failures by comparing code-derived expectations with real browser behavior
+
+🧠 Extracts expectations from source code using static analysis:
+
+Navigation from HTML links and React Router / Next.js routes
+
+Network actions from fetch / axios calls with static URLs
+
+State mutations from React useState, Redux dispatch, and Zustand set
+
+🖱️ Observes websites like a real user using Playwright (clicks, forms, navigation, scrolling)
+
+📊 Assigns confidence levels (HIGH / MEDIUM / LOW) based on evidence strength
+
+🧾 Provides clear evidence for every finding:
+
+Screenshots
+
+Network activity
+
+Console errors
+
+DOM and state changes
+
+💻 Runs as a CLI tool with verax scan and verax flow
+
+🧱 Supports real-world projects:
+
+Static HTML sites
+
+React SPAs
+
+Next.js (App Router & Pages Router)
+
+🔐 Protects privacy by automatically redacting secrets and sensitive data
+
+🚫 What VERAX does NOT do
+
+❌ Does not guess intent — no heuristics, no assumptions
+
+❌ Does not support dynamic routes (/user/${id} is intentionally skipped)
+
+❌ Does not replace QA or tests — it complements them
+
+❌ Does not monitor production traffic
+
+❌ Does not work for every framework
+
+❌ Does not detect every bug — only silent failures backed by code promises
+
+❌ Does not use AI — all results are deterministic and explainable
+
+🔄 How VERAX works (high-level)
+
+VERAX runs three phases automatically:
+
+1️⃣ Learn
+
+Analyzes your source code to understand:
+
+Project structure
+
+Routes
+
+What interactions promise to do
+Creates a manifest of expectations derived directly from code.
+
+2️⃣ Observe
+
+Opens your site in a real browser and interacts naturally:
+
+Clicks buttons
+
+Fills forms
+
+Follows links
+Records what actually happens.
+
+3️⃣ Detect
+
+Compares code expectations with real behavior.
+Reports a finding only when code promised an outcome that did not occur — with evidence and confidence.
+
+You run one command. VERAX handles the rest.
+
+📦 Installation
+
+Requirements: Node.js 18+
+
+From npm (when published):
+npm install -g @verax/verax
+
+From source:
+git clone <repository-url>
+cd odavlguardian
+npm install
+npm link
+
+🚀 Basic usage
+Scan a website:
+verax scan --url <http://localhost:3000>
+
+JSON output (CI-friendly):
+verax scan --url <http://localhost:3000> --json
+
+Scan a specific project directory:
+verax scan --url <http://localhost:3000> --projectRoot ./my-website
+
+Execute a user flow:
+verax flow --flow ./flows/login.json --url <http://localhost:3000>
+
+Outputs
+
+Artifacts are written to:
+
+.verax/runs/<runId>/
+
+Includes:
+
+summary.json — overall results
+
+findings.json — detected issues with evidence
+
+traces.jsonl — interaction traces
+
+evidence/ — screenshots and logs
+
+Exit codes
+
+0 — No HIGH confidence findings
+
+1 — MEDIUM / LOW findings only
+
+2 — At least one HIGH confidence finding
+
+3 — Fatal error
+
+📊 Understanding results
+
+Each finding includes:
+
+Type — what kind of failure occurred
+
+Reason — plain English explanation
+
+Confidence — score (0–100) + level
+
+Evidence — screenshots, network data, console logs
+
+Confidence levels:
+
+HIGH (80–100) — strong, unambiguous evidence
+
+MEDIUM (60–79) — likely failure with some ambiguity
+
+LOW (<60) — weak or partial evidence
+
+VERAX prefers missing an issue over reporting a false one.
+
+🔐 Safety and privacy
+
+🔒 No guessing
+
+🧹 Automatic redaction of secrets and personal data
+
+🛑 Safe by default — blocks destructive actions unless explicitly allowed
+
+🧭 Flows are opt-in only — nothing runs without your definition
+
+🎯 When VERAX is a good fit
+
+Marketing and public-facing websites
+
+SaaS signup and pricing flows
+
+React and Next.js projects
+
+CI pipelines that need UX validation
+
+Teams that value evidence over assumptions
+
+🚫 When VERAX is NOT a good fit
+
+Internal admin dashboards
+
+Authentication-heavy systems
+
+Apps built around highly dynamic routing
+
+Unsupported frameworks
+
+Teams expecting a full QA replacement
+
+🧪 Project status
+
+VERAX is a production-grade CLI tool in active development.
+It is designed for early adopters and technical teams.
+
+VERAX is not a SaaS product.
+It runs locally or in CI. There is no hosted service.
+
+📄 License
+
+MIT

package/bin/verax.js

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'fs';
+import inquirer from 'inquirer';
+import { learn } from '../src/verax/index.js';
+import { resolveWorkspaceRoot } from '../src/verax/resolve-workspace-root.js';
+import { initArtifactPaths, writeSummary, writeFindings, appendTrace } from '../src/verax/shared/artifact-manager.js';
+import { redactFinding, redactTrace } from '../src/verax/shared/redaction.js';
+import { initMetrics, recordMetric, getMetrics } from '../src/verax/shared/timing-metrics.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  // Handle Wave 9 CLI commands
+  if (command === 'scan') {
+    await handleScan(args.slice(1));
+    return;
+  }
+
+  if (command === 'flow') {
+    await handleFlow(args.slice(1));
+    return;
+  }
+
+  if (['--help', '-h', 'help'].includes(command)) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Default: interactive mode (existing behavior)
+  console.log('VERAX\n');
+
+  // Reuse parsed args from above for optional flags
+  let projectDir = null;
+  let url = null;
+  let manifestPath = null;
+  
+  const projectDirIndex = args.indexOf('--project-dir');
+  const projectDirArg = projectDirIndex !== -1 && args[projectDirIndex + 1] ? args[projectDirIndex + 1] : null;
+  
+  const urlIndex = args.indexOf('--url');
+  if (urlIndex !== -1 && urlIndex + 1 < args.length) {
+    url = args[urlIndex + 1];
+  }
+  
+  const manifestIndex = args.indexOf('--manifest');
+  if (manifestIndex !== -1 && manifestIndex + 1 < args.length) {
+    manifestPath = resolve(args[manifestIndex + 1]);
+  }
+
+  // Resolve workspace root using the new function
+  try {
+    const resolved = resolveWorkspaceRoot(projectDirArg, process.cwd());
+    projectDir = resolved.workspaceRoot;
+    
+    if (resolved.isRepoRoot) {
+      console.error(
+        'VERAX: Refusing to write artifacts in repository root.\n' +
+        'Use --project-dir to specify the target project directory.'
+      );
+      process.exit(2);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(2);
+  }
+
+  const actions = ['Scan my website'];
+  let action;
+  
+  if (actions.length === 1) {
+    action = actions[0];
+  } else {
+    const result = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: 'What would you like to do?',
+        choices: actions,
+        default: actions[0]
+      }
+    ]);
+    action = result.action;
+  }
+
+  if (action === 'Scan my website') {
+    try {
+      console.log('Understanding your website...');
+      const manifest = await learn(projectDir);
+      
+      console.log(`\nProject type: ${manifest.projectType}`);
+      console.log(`Total routes: ${manifest.routes.length}`);
+      console.log(`Public routes: ${manifest.publicRoutes.length}`);
+      console.log(`Internal routes: ${manifest.internalRoutes.length}`);
+      
+      if (url) {
+        const { scan } = await import('../src/verax/index.js');
+        const result = await scan(projectDir, url, manifestPath);
+        const { observation, findings, scanSummary } = result;
+        
+        console.log('\nObserving real user interactions...');
+        console.log('Comparing expectations with reality...');
+        
+        console.log('\nScan complete.\n');
+        console.log(`Total interactions observed: ${observation.traces.length}`);
+        console.log(`Silent failures detected: ${findings.findings.length}`);
+        
+        if (findings.findings.length > 0) {
+          console.log(`\nFindings report: ${findings.findingsPath}\n`);
+        } else {
+          console.log('\nNo silent user failures were detected.');
+          console.log(`\nFindings report: ${findings.findingsPath}\n`);
+        }
+        
+        if (scanSummary) {
+          const truth = scanSummary.truth;
+          console.log('Truth Summary:');
+          console.log(`- Learn: routes=${truth.learn.routesDiscovered} (confidence: ${truth.learn.routesConfidence}, source: ${truth.learn.routesSource}), expectations=${truth.learn.expectationsDiscovered} (strong=${truth.learn.expectationsStrong}, weak=${truth.learn.expectationsWeak})`);
+          if (truth.learn.validation) {
+            console.log(`- Learn validation: validated=${truth.learn.validation.routesValidated}, reachable=${truth.learn.validation.routesReachable}, unreachable=${truth.learn.validation.routesUnreachable}`);
+          }
+          const coverage = truth.observe.coverage;
+          const coverageLine = coverage
+            ? `Coverage: selected=${coverage.candidatesSelected}/${coverage.candidatesDiscovered} (cap=${coverage.cap})${coverage.capped ? ' — capped' : ''}`
+            : null;
+          console.log(`- Observe: interactions=${truth.observe.interactionsObserved}, external-blocked=${truth.observe.externalNavigationBlockedCount}, timeouts=${truth.observe.timeoutsCount}`);
+          if (coverageLine) {
+            console.log(`  - ${coverageLine}`);
+          }
+          console.log(`- Detect: analyzed=${truth.detect.interactionsAnalyzed}, skipped(no expectation)=${truth.detect.interactionsSkippedNoExpectation}, findings=${truth.detect.findingsCount}`);
+          if (truth.detect.skips && truth.detect.skips.total > 0) {
+            const topReasons = truth.detect.skips.reasons.slice(0, 3).map(r => `${r.code}=${r.count}`).join(', ');
+            console.log(`- Detect skips: ${truth.detect.skips.total} (top: ${topReasons})`);
+          }
+          console.log(`- Scan summary: ${scanSummary.summaryPath}\n`);
+        }
+      } else {
+        console.log('\nNote: Provide --url to observe website interactions\n');
+      }
+      
+      process.exit(0);
+    } catch (error) {
+      console.error(`\nError: ${error.message}`);
+      if (error.stack && process.env.DEBUG) {
+        console.error(error.stack);
+      }
+      process.exit(2);
+    }
+  }
+}
+
+/**
+ * Parse command-line arguments into key-value object
+ */
+function parseArgs(argArray) {
+  const opts = {};
+  for (let i = 0; i < argArray.length; i++) {
+    if (argArray[i].startsWith('--')) {
+      const key = argArray[i].substring(2);
+      if (i + 1 < argArray.length && !argArray[i + 1].startsWith('--')) {
+        opts[key] = argArray[i + 1];
+        i++;
+      } else {
+        opts[key] = true;
+      }
+    }
+  }
+  return opts;
+}
+
+/**
+ * Print help message
+ */
+function printHelp() {
+  console.log(`
+VERAX — Web Application Verification Platform
+
+Usage:
+  verax [interactive]                           Interactive mode
+  verax scan --url <url> [--projectRoot <path>] [--json] [--out <dir>]
+  verax flow --flow <path> [--url <url>] [--json] [--out <dir>]
+  verax --help                                  Show this message
+
+Commands:
+  scan                Run full scan on a live URL
+  flow                Execute a user flow against a URL
+
+Options:
+  --url <url>         Target URL
+  --flow <path>       Path to flow definition file
+  --projectRoot <p>   Project root directory (defaults to cwd)
+  --json              Output machine-readable JSON
+  --out <dir>         Output directory (defaults to .verax/runs)
+  --help, -h          Show this help
+
+Exit Codes:
+  0                   No HIGH findings
+  1                   MEDIUM/LOW findings only
+  2                   At least one HIGH finding
+  3                   Fatal error
+`);
+}
+
+/**
+ * Handle 'verax scan' command - integrated with main pipeline
+ */
+async function handleScan(scanArgs) {
+  const opts = parseArgs(scanArgs);
+
+  if (!opts.url) {
+    console.error('Error: --url is required');
+    process.exit(3);
+  }
+
+  const projectRoot = opts.projectRoot || process.cwd();
+  const url = opts.url;
+  const jsonOutput = opts.json === true || opts.json === 'true';
+  const outDir = opts.out;
+
+  try {
+    initMetrics();
+    const startTime = Date.now();
+
+    // Initialize artifact paths
+    const artifactPaths = outDir 
+      ? { runDir: outDir, summary: `${outDir}/summary.json`, findings: `${outDir}/findings.json`, traces: `${outDir}/traces.jsonl` }
+      : initArtifactPaths(projectRoot);
+
+    // Ensure artifact directories exist
+    mkdirSync(artifactPaths.runDir, { recursive: true });
+
+    // Run the full VERAX pipeline using the scan() orchestrator
+    console.error(`[VERAX] Starting scan for ${url}`);
+    const resolvedRootResult = await resolveWorkspaceRoot(projectRoot);
+    const resolvedRoot = resolvedRootResult.workspaceRoot;
+
+    const scanStart = Date.now();
+    const { scan } = await import('../src/verax/index.js');
+    const result = await scan(resolvedRoot, url, null, artifactPaths.runId);
+    recordMetric('totalMs', Date.now() - scanStart);
+
+    const manifest = result.manifest;
+    const observation = result.observation;
+    const findings = result.findings;
+
+    const metrics = getMetrics();
+    metrics.totalMs = Date.now() - startTime;
+
+    // Count findings by level
+    const findingsList = findings?.findings || [];
+    const findingsCounts = {
+      HIGH: findingsList.filter(f => f.confidence?.level === 'HIGH').length,
+      MEDIUM: findingsList.filter(f => f.confidence?.level === 'MEDIUM').length,
+      LOW: findingsList.filter(f => f.confidence?.level === 'LOW').length,
+      UNKNOWN: findingsList.filter(f => !f.confidence?.level || f.confidence?.level === 'UNKNOWN').length
+    };
+
+    // Get top findings
+    const topFindings = findingsList
+      .slice(0, 3)
+      .map(f => ({
+        type: f.type,
+        reason: f.reason,
+        confidence: f.confidence?.score || 0
+      }));
+    
+    // Write summary with metrics to artifact paths
+        writeSummary(artifactPaths, {
+          url,
+          projectRoot: resolvedRoot,
+          metrics,
+          findingsCounts,
+          topFindings
+        });
+
+    // Determine exit code
+    const HIGH_COUNT = findingsCounts.HIGH;
+    const hasAny = Object.values(findingsCounts).reduce((a, b) => a + b, 0) > 0;
+
+    if (jsonOutput) {
+      const summary = {
+        runId: artifactPaths.runId,
+        url,
+        metrics,
+        findingsCounts,
+        topFindings,
+        total: findingsList.length
+      };
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.error(`[VERAX] Scan complete in ${(metrics.totalMs / 1000).toFixed(2)}s`);
+      console.error(`[VERAX] Findings: HIGH=${HIGH_COUNT}, MEDIUM=${findingsCounts.MEDIUM}, LOW=${findingsCounts.LOW}`);
+      if (topFindings.length > 0) {
+        console.error(`[VERAX] Top findings:`);
+        topFindings.forEach(f => {
+          console.error(`  - [${f.confidence}%] ${f.type}: ${f.reason}`);
+        });
+      }
+    }
+
+    // Exit with appropriate code
+    if (HIGH_COUNT > 0) {
+      process.exit(2);
+    } else if (hasAny) {
+      process.exit(1);
+    } else {
+      process.exit(0);
+    }
+  } catch (error) {
+    if (!jsonOutput) {
+      console.error(`[VERAX] Scan failed: ${error.message}`);
+    }
+    process.exit(3);
+  }
+}
+
+/**
+ * Handle 'verax flow' command - execute a user flow
+ */
+async function handleFlow(flowArgs) {
+  const opts = parseArgs(flowArgs);
+
+  if (!opts.flow) {
+    console.error('Error: --flow is required');
+    process.exit(3);
+  }
+
+  const flowPath = resolve(opts.flow);
+  if (!existsSync(flowPath)) {
+    console.error(`Error: Flow file not found: ${flowPath}`);
+    process.exit(3);
+  }
+
+  const url = opts.url;
+
+  const jsonOutput = opts.json === true || opts.json === 'true';
+  const projectRoot = opts.projectRoot || process.cwd();
+  const outDir = opts.out;
+
+  try {
+    initMetrics();
+    const startTime = Date.now();
+
+    // Initialize artifact paths
+    const artifactPaths = outDir 
+      ? { runDir: outDir, flows: `${outDir}/flows` }
+      : initArtifactPaths(projectRoot);
+    mkdirSync(artifactPaths.runDir, { recursive: true });
+    if (artifactPaths.flows) {
+      mkdirSync(artifactPaths.flows, { recursive: true });
+    }
+
+    // Load and validate flow spec
+    const { readFileSync } = await import('fs');
+    const flowContent = readFileSync(flowPath, 'utf-8');
+    const flowSpec = JSON.parse(flowContent);
+    
+    // Override baseUrl with --url if provided
+    if (url) {
+      flowSpec.baseUrl = url;
+    }
+    
+    const { validateFlowSpec } = await import('../src/verax/flow/flow-spec.js');
+    const validatedSpec = validateFlowSpec(flowSpec);
+    
+    // Use baseUrl from spec for navigation
+    const targetUrl = validatedSpec.baseUrl;
+
+    // Create browser and sensors
+    const { createBrowser, navigateToUrl, closeBrowser } = await import('../src/verax/observe/browser.js');
+    const { NetworkSensor } = await import('../src/verax/observe/network-sensor.js');
+    const { ConsoleSensor } = await import('../src/verax/observe/console-sensor.js');
+    const { UISignalSensor } = await import('../src/verax/observe/ui-signal-sensor.js');
+    
+    const { browser, page } = await createBrowser();
+    const sensors = {
+      network: new NetworkSensor(),
+      console: new ConsoleSensor(),
+      uiSignals: new UISignalSensor()
+    };
+
+    try {
+      await navigateToUrl(page, targetUrl);
+      
+      // Execute flow
+      const { executeFlow } = await import('../src/verax/flow/flow-engine.js');
+      const flowResult = await executeFlow(page, validatedSpec, sensors);
+
+      await closeBrowser(browser);
+
+      recordMetric('totalMs', Date.now() - startTime);
+      const metrics = getMetrics();
+
+      // Write flow results
+      const flowResultsPath = resolve(artifactPaths.flows || artifactPaths.runDir, 'flow-results.json');
+      writeFileSync(flowResultsPath, JSON.stringify({
+        flow: validatedSpec.name,
+        url: targetUrl,
+        success: flowResult.success,
+        findings: flowResult.findings,
+        stepResults: flowResult.stepResults,
+        metrics
+      }, null, 2) + '\n');
+
+      if (jsonOutput) {
+        console.log(JSON.stringify({
+          flow: validatedSpec.name,
+          url: targetUrl,
+          success: flowResult.success,
+          findingsCount: flowResult.findings.length,
+          metrics
+        }, null, 2));
+      } else {
+        console.error(`[VERAX] Flow execution complete in ${(metrics.totalMs / 1000).toFixed(2)}s`);
+        console.error(`[VERAX] Flow: ${validatedSpec.name}`);
+        console.error(`[VERAX] Success: ${flowResult.success}`);
+        console.error(`[VERAX] Findings: ${flowResult.findings.length}`);
+        if (flowResult.findings.length > 0) {
+          flowResult.findings.forEach((f, i) => {
+            console.error(`  ${i + 1}. [Step ${f.stepIndex}] ${f.type}: ${f.reason}`);
+          });
+        }
+      }
+
+      // Exit code: 0 if success, 2 if findings, 3 if error
+      if (!flowResult.success) {
+        process.exit(2);
+      } else {
+        process.exit(0);
+      }
+    } catch (error) {
+      await closeBrowser(browser);
+      throw error;
+    }
+  } catch (error) {
+    if (!jsonOutput) {
+      console.error(`[VERAX] Flow execution failed: ${error.message}`);
+    }
+    process.exit(3);
+  }
+}
+
+main().catch((error) => {
+  console.error(`Fatal error: ${error.message}`);
+  process.exit(2);
+});