@veraxhq/verax 0.1.0

package/src/verax/observe/human-driver.js

@@ -0,0 +1,376 @@
+/**
+ * WAVE 2: Human Behavior Driver
+ * Realistic interaction execution with scrolling, form filling, and budgeting
+ */
+
+import { waitForSettle } from './settle.js';
+
+export class HumanBehaviorDriver {
+  constructor(options = {}) {
+    this.maxScrollSteps = options.maxScrollSteps || 5;
+    this.interactionBudgetPerPage = options.interactionBudgetPerPage || 50;
+    this.scrollPauseMs = options.scrollPauseMs || 500;
+  }
+
+  /**
+   * Discover all interactive elements on current page with scrolling.
+   * Returns stable set of unique elements after scroll-and-rediscover passes.
+   */
+  async discoverInteractionsWithScroll(page) {
+    const discovered = new Map(); // key: selector, value: element data
+
+    // Initial discovery before any scrolling
+    await this.discoverElements(page, discovered);
+
+    // Progressive scrolling discovery
+    const viewportHeight = await page.evaluate(() => window.innerHeight);
+    const maxScrollDistance = await page.evaluate(() => document.documentElement.scrollHeight);
+
+    for (let step = 0; step < this.maxScrollSteps; step++) {
+      // Calculate scroll position (0%, 25%, 50%, 75%, 100%)
+      const scrollPercent = (step + 1) / this.maxScrollSteps;
+      const targetScroll = Math.min(maxScrollDistance, scrollPercent * maxScrollDistance);
+
+      await page.evaluate((scroll) => window.scrollTo(0, scroll), targetScroll);
+      await page.waitForTimeout(this.scrollPauseMs);
+
+      // Rediscover after scroll
+      await this.discoverElements(page, discovered);
+    }
+
+    // Return to top
+    await page.evaluate(() => window.scrollTo(0, 0));
+
+    return Array.from(discovered.values());
+  }
+
+  /**
+   * Discover interactive elements and merge into stable map.
+   * Handles: links, buttons, forms, role=button elements
+   */
+  async discoverElements(page, discovered) {
+    const elements = await page.evaluate(() => {
+      const result = [];
+
+      // Links
+      document.querySelectorAll('a[href]').forEach((el) => {
+        if (isVisible(el) && !el.hasAttribute('data-skip-verify')) {
+          result.push({
+            type: 'link',
+            selector: generateSelector(el),
+            href: el.getAttribute('href'),
+            text: el.textContent.trim().slice(0, 100),
+            visible: true
+          });
+        }
+      });
+
+      // Buttons
+      document.querySelectorAll('button').forEach((el) => {
+        if (isVisible(el) && !el.hasAttribute('data-skip-verify')) {
+          result.push({
+            type: 'button',
+            selector: generateSelector(el),
+            text: el.textContent.trim().slice(0, 100),
+            visible: true
+          });
+        }
+      });
+
+      // Form inputs
+      document.querySelectorAll('input[type="submit"], input[type="button"]').forEach((el) => {
+        if (isVisible(el) && !el.hasAttribute('data-skip-verify')) {
+          result.push({
+            type: 'button',
+            selector: generateSelector(el),
+            text: el.value || el.getAttribute('title') || 'Submit',
+            visible: true
+          });
+        }
+      });
+
+      // Role=button elements
+      document.querySelectorAll('[role="button"]').forEach((el) => {
+        if (isVisible(el) && !el.hasAttribute('data-skip-verify')) {
+          result.push({
+            type: 'button',
+            selector: generateSelector(el),
+            text: el.textContent.trim().slice(0, 100),
+            visible: true
+          });
+        }
+      });
+
+      return result;
+
+      // Helper: Check if element is visible
+      function isVisible(el) {
+        if (!el.offsetParent) return false;
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden') return false;
+        return true;
+      }
+
+      // Helper: Generate stable selector
+      function generateSelector(el) {
+        // Try ID first
+        if (el.id) return `#${el.id}`;
+
+        // Try data attributes
+        if (el.dataset.testid) return `[data-testid="${el.dataset.testid}"]`;
+
+        // Use CSS selector generation
+        const path = [];
+        let current = el;
+        while (current && current !== document.documentElement) {
+          let selector = current.tagName.toLowerCase();
+          if (current.id) {
+            selector += `#${current.id}`;
+            path.unshift(selector);
+            break;
+          }
+
+          // Add class if present
+          if (current.className) {
+            const classes = current.className
+              .split(' ')
+              .filter((c) => c && !c.startsWith('__'))
+              .join('.');
+            if (classes) selector += `.${classes}`;
+          }
+
+          // Add nth-child for uniqueness
+          let sibling = current;
+          let index = 0;
+          while (sibling) {
+            if (sibling.tagName === current.tagName) index++;
+            sibling = sibling.previousElementSibling;
+          }
+          if (index > 0) selector += `:nth-of-type(${index})`;
+
+          path.unshift(selector);
+          current = current.parentElement;
+        }
+
+        return path.join(' > ');
+      }
+    });
+
+    // Merge into stable map (deduplicate by selector)
+    for (const el of elements) {
+      if (!discovered.has(el.selector)) {
+        discovered.set(el.selector, el);
+      }
+    }
+  }
+
+  /**
+   * Select interactions according to budget with deterministic prioritization.
+   * Returns { selected, skipped, budget }
+   */
+  selectByBudget(discovered) {
+    const selected = [];
+    const skipped = [];
+
+    // Sort deterministically: by priority category, then text/href for stability
+    const sorted = discovered.sort((a, b) => {
+      const priorityA = getPriority(a);
+      const priorityB = getPriority(b);
+      if (priorityA !== priorityB) return priorityA - priorityB;
+
+      const textA = (a.text || a.href || '').toLowerCase();
+      const textB = (b.text || b.href || '').toLowerCase();
+      return textA.localeCompare(textB);
+    });
+
+    // Allocate budget across categories
+    const categories = { link: [], button: [], form: [] };
+    for (const el of sorted) {
+      const cat = el.type === 'link' ? 'link' : 'button';
+      categories[cat].push(el);
+    }
+
+    // Distribute budget: 40% links, 40% buttons, 20% forms
+    const linkBudget = Math.floor(this.interactionBudgetPerPage * 0.4);
+    const buttonBudget = Math.floor(this.interactionBudgetPerPage * 0.4);
+    const formBudget = Math.floor(this.interactionBudgetPerPage * 0.2);
+
+    for (let i = 0; i < categories.link.length; i++) {
+      if (i < linkBudget) selected.push(categories.link[i]);
+      else skipped.push(categories.link[i]);
+    }
+
+    for (let i = 0; i < categories.button.length; i++) {
+      if (i < buttonBudget) selected.push(categories.button[i]);
+      else skipped.push(categories.button[i]);
+    }
+
+    return {
+      selected,
+      skipped,
+      discoveredCount: discovered.length,
+      selectedCount: selected.length,
+      skippedDueToBudgetCount: skipped.length,
+      budgetUsed: selected.length,
+      budgetAvailable: this.interactionBudgetPerPage
+    };
+  }
+
+  /**
+   * Fill and submit a form with realistic dummy data.
+   * Respects safety rules: skips payment, checkout, delete, etc.
+   */
+  async fillAndSubmitForm(page, formSelector) {
+    // Check safety rules first
+    const isDangerous = await page.evaluate((sel) => {
+      const form = document.querySelector(sel);
+      if (!form) return true;
+
+      const text = form.textContent.toLowerCase();
+      const dangerousKeywords = ['pay', 'checkout', 'delete', 'remove', 'unsubscribe', 'billing', 'credit card'];
+      if (dangerousKeywords.some((kw) => text.includes(kw))) return true;
+
+      // Check buttons
+      const buttons = form.querySelectorAll('button, input[type="submit"]');
+      for (const btn of buttons) {
+        const btnText = btn.textContent.toLowerCase();
+        if (dangerousKeywords.some((kw) => btnText.includes(kw))) return true;
+      }
+
+      return false;
+    }, formSelector);
+
+    if (isDangerous) {
+      return { success: false, reason: 'DANGEROUS_FORM_SKIPPED' };
+    }
+
+    // Fill required fields
+    const filled = await page.evaluate((sel) => {
+      const form = document.querySelector(sel);
+      if (!form) return { filled: [], errors: [] };
+
+      const filled = [];
+      const errors = [];
+
+      // Find all input elements
+      const inputs = form.querySelectorAll('input, textarea, select');
+
+      for (const input of inputs) {
+        if (input.disabled || input.readOnly) continue;
+        if (input.type === 'hidden' || input.type === 'submit' || input.type === 'button') continue;
+
+        try {
+          if (input.tagName === 'SELECT') {
+            // Choose first non-empty option
+            const options = input.querySelectorAll('option');
+            if (options.length > 1) {
+              input.value = options[1].value;
+              input.dispatchEvent(new Event('change', { bubbles: true }));
+              filled.push({ name: input.name || input.id || 'select', value: input.value });
+            }
+          } else if (input.type === 'checkbox' || input.type === 'radio') {
+            // Choose first option
+            input.checked = true;
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+            filled.push({ name: input.name || input.id || 'checkbox', value: 'checked' });
+          } else if (input.type === 'email') {
+            input.value = 'test@example.com';
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+            filled.push({ name: input.name || input.id || 'email', value: 'test@example.com' });
+          } else if (input.type === 'tel') {
+            input.value = '+1-555-0123';
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+            filled.push({ name: input.name || input.id || 'tel', value: '+1-555-0123' });
+          } else if (input.type === 'url') {
+            input.value = 'https://example.com';
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+            filled.push({ name: input.name || input.id || 'url', value: 'https://example.com' });
+          } else if (input.tagName === 'TEXTAREA') {
+            input.value = 'Test message';
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+            filled.push({ name: input.name || input.id || 'textarea', value: 'Test message' });
+          } else if (input.type === 'text' || input.type === '') {
+            // Guess based on name/label
+            const name = (input.name || input.id || '').toLowerCase();
+            let value = 'John Doe';
+            if (name.includes('email')) value = 'test@example.com';
+            else if (name.includes('name')) value = 'John Doe';
+            else if (name.includes('phone') || name.includes('tel')) value = '+1-555-0123';
+            else if (name.includes('address') || name.includes('street')) value = '123 Main St';
+            else if (name.includes('city')) value = 'Anytown';
+            else if (name.includes('state') || name.includes('province')) value = 'CA';
+            else if (name.includes('zip') || name.includes('postal')) value = '12345';
+
+            input.value = value;
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+            filled.push({ name: input.name || input.id || 'text', value });
+          }
+        } catch (err) {
+          errors.push({ name: input.name || input.id, error: err.message });
+        }
+      }
+
+      return { filled, errors };
+    }, formSelector);
+
+    // Submit form
+    const submitResult = await page.evaluate((sel) => {
+      const form = document.querySelector(sel);
+      if (!form) return { submitted: false, reason: 'FORM_NOT_FOUND' };
+
+      // Find submit button
+      let submitBtn = form.querySelector('button[type="submit"], input[type="submit"]');
+
+      if (!submitBtn) {
+        // Try click form submit
+        form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+        return { submitted: true, method: 'form_submit_event' };
+      }
+
+      // Click submit button
+      submitBtn.click();
+      return { submitted: true, method: 'button_click' };
+    }, formSelector);
+
+    // Wait for navigation or settle
+    try {
+      await Promise.race([
+        page.waitForNavigation({ waitUntil: 'networkidle', timeout: 5000 }).catch(() => {}),
+        page.waitForTimeout(2000)
+      ]);
+    } catch {
+      // Navigation may not happen, that's okay
+    }
+
+    await waitForSettle(page, { timeoutMs: 10000 });
+
+    return {
+      success: true,
+      filled: filled.filled,
+      submitted: submitResult.submitted,
+      method: submitResult.method
+    };
+  }
+}
+
+/**
+ * Get deterministic priority for interaction.
+ * Lower number = higher priority
+ */
+function getPriority(element) {
+  const text = (element.text || element.href || '').toLowerCase();
+
+  // Primary navigation
+  if (text.includes('home') || text.includes('/')) return 0;
+  if (text.includes('about')) return 1;
+  if (text.includes('contact')) return 2;
+  if (text.includes('service') || text.includes('product')) return 3;
+  if (text.includes('blog') || text.includes('news')) return 4;
+
+  // Footer/secondary
+  if (text.includes('footer') || text.includes('copyright')) return 100;
+  if (text.includes('privacy') || text.includes('terms')) return 101;
+
+  // Default
+  return 50;
+}

package/src/verax/observe/index.js

@@ -0,0 +1,67 @@
+import { resolve, dirname } from 'path';
+import { mkdirSync } from 'fs';
+import { createBrowser, navigateToUrl, closeBrowser } from './browser.js';
+import { discoverInteractions } from './interaction-discovery.js';
+import { captureScreenshot } from './evidence-capture.js';
+import { runInteraction } from './interaction-runner.js';
+import { writeTraces } from './traces-writer.js';
+import { getBaseOrigin } from './domain-boundary.js';
+
+const MAX_SCAN_DURATION_MS = 60000;
+
+export async function observe(url, manifestPath = null, artifactPaths = null) {
+  const { browser, page } = await createBrowser();
+  const startTime = Date.now();
+  const baseOrigin = getBaseOrigin(url);
+  
+  try {
+    await navigateToUrl(page, url);
+    
+    const projectDir = manifestPath ? dirname(dirname(dirname(manifestPath))) : process.cwd();
+    let screenshotsDir;
+    if (artifactPaths) {
+      screenshotsDir = resolve(artifactPaths.evidence, 'screenshots');
+    } else {
+      const observeDir = resolve(projectDir, '.veraxverax', 'observe');
+      screenshotsDir = resolve(observeDir, 'screenshots');
+    }
+    mkdirSync(screenshotsDir, { recursive: true });
+    
+    const timestamp = Date.now();
+    const initialScreenshot = resolve(screenshotsDir, `initial-${timestamp}.png`);
+    await captureScreenshot(page, initialScreenshot);
+    
+    const { interactions, coverage } = await discoverInteractions(page, baseOrigin);
+    const traces = [];
+    const observeWarnings = [];
+    if (coverage && coverage.capped) {
+      observeWarnings.push({
+        code: 'INTERACTIONS_CAPPED',
+        message: 'Interaction discovery reached the cap (30). Scan coverage is incomplete.'
+      });
+    }
+    
+    for (let i = 0; i < interactions.length; i++) {
+      if (Date.now() - startTime > MAX_SCAN_DURATION_MS) {
+        break;
+      }
+      
+      const trace = await runInteraction(page, interactions[i], timestamp, i, screenshotsDir, baseOrigin, startTime, MAX_SCAN_DURATION_MS);
+      if (trace) {
+        traces.push(trace);
+      }
+    }
+    
+    const observation = writeTraces(projectDir, url, traces, coverage, observeWarnings, artifactPaths);
+    
+    await closeBrowser(browser);
+    
+    return {
+      ...observation,
+      screenshotsDir: screenshotsDir
+    };
+  } catch (error) {
+    await closeBrowser(browser);
+    throw error;
+  }
+}