@veraxhq/verax 0.1.0

package/src/verax/detect/skip-classifier.js

@@ -0,0 +1,202 @@
+import { getUrlPath } from './evidence-validator.js';
+
+const MAX_EXAMPLES = 10;
+
+export function classifySkipReason(manifest, interaction, beforeUrl, validation = null) {
+  const skipReasons = {
+    NO_EXPECTATION: {
+      code: 'NO_EXPECTATION',
+      message: 'No applicable expectations found for this interaction type or context'
+    },
+    AMBIGUOUS_MATCH: {
+      code: 'AMBIGUOUS_MATCH',
+      message: 'Multiple expectations could match; conservative approach requires single clear match'
+    },
+    SELECTOR_MISMATCH: {
+      code: 'SELECTOR_MISMATCH',
+      message: 'Expectations exist but selector mismatch and no safe fallback match'
+    },
+    WEAK_EXPECTATION_DROPPED: {
+      code: 'WEAK_EXPECTATION_DROPPED',
+      message: 'Expectation derived from route that was validated as unreachable'
+    },
+    UNSUPPORTED_INTERACTION: {
+      code: 'UNSUPPORTED_INTERACTION',
+      message: 'Interaction type not supported for expectation derivation'
+    }
+  };
+  
+  const beforePath = getUrlPath(beforeUrl);
+  const normalizedBefore = beforePath ? beforePath.replace(/\/$/, '') || '/' : null;
+  
+  let hasStaticExpectations = false;
+  let hasRouteExpectations = false;
+  let hasMatchingStaticExpectations = false;
+  let selectorMismatchCount = 0;
+  let matchingRoutes = [];
+  let unreachableRoutes = new Set();
+  
+  if (validation && validation.details) {
+    for (const detail of validation.details) {
+      if (detail.status === 'UNREACHABLE') {
+        unreachableRoutes.add(detail.path);
+      }
+    }
+  }
+  
+  if (manifest.staticExpectations && manifest.staticExpectations.length > 0) {
+    hasStaticExpectations = true;
+    for (const expectation of manifest.staticExpectations) {
+      if (normalizedBefore && expectation.fromPath.replace(/\/$/, '') || '/' === normalizedBefore) {
+        if (expectation.type === 'navigation' && (interaction.type === 'link' || interaction.type === 'button')) {
+          hasMatchingStaticExpectations = true;
+          const selectorHint = expectation.evidence.selectorHint || '';
+          const interactionSelector = interaction.selector || '';
+          
+          if (selectorHint && interactionSelector) {
+            const normalizedSelectorHint = selectorHint.replace(/[\[\]()]/g, '');
+            const normalizedInteractionSelector = interactionSelector.replace(/[\[\]()]/g, '');
+            
+            if (selectorHint === interactionSelector || 
+                selectorHint.includes(interactionSelector) || 
+                interactionSelector.includes(normalizedSelectorHint) ||
+                normalizedSelectorHint === normalizedInteractionSelector) {
+              return null;
+            } else {
+              selectorMismatchCount++;
+            }
+          } else if (!selectorHint && !interactionSelector) {
+            return null;
+          } else {
+            selectorMismatchCount++;
+          }
+        } else if (expectation.type === 'form_submission' && interaction.type === 'form') {
+          hasMatchingStaticExpectations = true;
+          const selectorHint = expectation.evidence.selectorHint || '';
+          const interactionSelector = interaction.selector || '';
+          
+          if (selectorHint && interactionSelector) {
+            const normalizedSelectorHint = selectorHint.replace(/[\[\]()]/g, '');
+            const normalizedInteractionSelector = interactionSelector.replace(/[\[\]()]/g, '');
+            
+            if (selectorHint === interactionSelector || 
+                selectorHint.includes(interactionSelector) || 
+                interactionSelector.includes(normalizedSelectorHint) ||
+                normalizedSelectorHint === normalizedInteractionSelector) {
+              return null;
+            } else {
+              selectorMismatchCount++;
+            }
+          } else {
+            selectorMismatchCount++;
+          }
+        }
+      }
+    }
+  }
+  
+  if (manifest.routes && manifest.routes.length > 0) {
+    hasRouteExpectations = true;
+    for (const route of manifest.routes) {
+      if (!route.public) continue;
+      if (unreachableRoutes.has(route.path)) {
+        continue;
+      }
+      
+      if (interaction.type === 'link') {
+        const label = (interaction.label || '').toLowerCase().trim();
+        const routePath = route.path.toLowerCase();
+        const routeName = routePath.split('/').pop() || 'home';
+        
+        if (label.includes(routeName) || routeName.includes(label)) {
+          matchingRoutes.push(route.path);
+        }
+      } else if (interaction.type === 'button' || interaction.type === 'form') {
+        const label = (interaction.label || '').toLowerCase().trim();
+        const routePath = route.path.toLowerCase();
+        const routeName = routePath.split('/').pop() || 'home';
+        
+        const navigationKeywords = ['go', 'navigate', 'next', 'continue', 'submit', 'save'];
+        const hasNavKeyword = navigationKeywords.some(keyword => label.includes(keyword));
+        
+        if (hasNavKeyword || label.includes(routeName) || routeName.includes(label)) {
+          matchingRoutes.push(route.path);
+        }
+      }
+    }
+  }
+  
+  if (hasMatchingStaticExpectations && selectorMismatchCount > 0) {
+    return skipReasons.SELECTOR_MISMATCH;
+  }
+  
+  if (matchingRoutes.length > 1) {
+    return skipReasons.AMBIGUOUS_MATCH;
+  }
+  
+  if (matchingRoutes.length === 1 && unreachableRoutes.has(matchingRoutes[0])) {
+    return skipReasons.WEAK_EXPECTATION_DROPPED;
+  }
+  
+  if (interaction.type === 'button' && !hasStaticExpectations && !hasRouteExpectations) {
+    const label = (interaction.label || '').toLowerCase().trim();
+    const navigationKeywords = ['go', 'navigate', 'next', 'continue', 'submit', 'save'];
+    const hasNavKeyword = navigationKeywords.some(keyword => label.includes(keyword));
+    
+    if (!hasNavKeyword) {
+      return skipReasons.UNSUPPORTED_INTERACTION;
+    }
+  }
+  
+  if (!hasStaticExpectations && !hasRouteExpectations) {
+    return skipReasons.NO_EXPECTATION;
+  }
+  
+  if (hasStaticExpectations && !hasMatchingStaticExpectations && !hasRouteExpectations) {
+    return skipReasons.NO_EXPECTATION;
+  }
+  
+  if (hasRouteExpectations && matchingRoutes.length === 0) {
+    return skipReasons.NO_EXPECTATION;
+  }
+  
+  return skipReasons.NO_EXPECTATION;
+}
+
+export function collectSkipReasons(skips) {
+  const reasonCounts = new Map();
+  const examples = [];
+  
+  for (const skip of skips) {
+    const code = skip.code;
+    reasonCounts.set(code, (reasonCounts.get(code) || 0) + 1);
+    
+    if (examples.length < MAX_EXAMPLES) {
+      examples.push({
+        interaction: {
+          type: skip.interaction.type,
+          selector: skip.interaction.selector ? skip.interaction.selector.substring(0, 100) : '',
+          label: skip.interaction.label ? skip.interaction.label.substring(0, 100) : ''
+        },
+        code: code,
+        message: skip.message
+      });
+    }
+  }
+  
+  const reasons = Array.from(reasonCounts.entries())
+    .map(([code, count]) => ({ code, count }))
+    .sort((a, b) => {
+      if (b.count !== a.count) {
+        return b.count - a.count;
+      }
+      return a.code.localeCompare(b.code);
+    });
+  
+  return {
+    total: skips.length,
+    reasons: reasons,
+    examples: examples
+  };
+}
+

package/src/verax/flow/flow-engine.js

@@ -0,0 +1,265 @@
+/**
+ * Wave 7 — Flow Engine
+ *
+ * Executes deterministic multi-step flows with strict safety gates.
+ * - No guessing: explicit selectors and expected outcomes only
+ * - Safety gates: denyKeywords, allowlist enforcement
+ * - Per-step sensor capture: network, console, UI signals
+ * - Deterministic: uses waitForSettle after each interactive step
+ */
+
+import { waitForSettle } from '../observe/settle.js';
+import { resolveSecrets, extractSecretValues } from './flow-spec.js';
+import { redactObject } from './redaction.js';
+
+/**
+ * Execute a flow on a Playwright page.
+ *
+ * @param {Object} page - Playwright page
+ * @param {Object} spec - Validated flow spec
+ * @param {Object} sensors - Sensor collectors {network, console, etc.}
+ * @returns {Promise<Object>} - {success, findings, stepResults}
+ */
+export async function executeFlow(page, spec, sensors = {}) {
+  const secretValues = extractSecretValues(spec.secrets);
+  const stepResults = [];
+  const findings = [];
+
+  try {
+    for (let idx = 0; idx < spec.steps.length; idx++) {
+      const step = spec.steps[idx];
+      const stepResult = await executeStep(page, step, idx, spec, sensors, secretValues);
+
+      stepResults.push(stepResult);
+
+      if (!stepResult.success) {
+        findings.push({
+          type: stepResult.findingType,
+          stepIndex: idx,
+          stepType: step.type,
+          reason: stepResult.reason,
+          evidence: redactObject(stepResult.evidence, secretValues)
+        });
+
+        // Stop on first failure
+        if (step.failureMode !== 'continue') {
+          break;
+        }
+      }
+    }
+  } catch (err) {
+    findings.push({
+      type: 'flow_step_failed',
+      stepIndex: -1,
+      reason: `Unexpected error: ${err.message}`,
+      evidence: { error: err.toString() }
+    });
+  }
+
+  return {
+    success: findings.length === 0,
+    findings,
+    stepResults: stepResults.map(r => redactObject(r, secretValues))
+  };
+}
+
+async function executeStep(page, step, idx, spec, sensors, secretValues) {
+  const baseResult = {
+    stepIndex: idx,
+    type: step.type,
+    success: false,
+    reason: '',
+    evidence: {}
+  };
+
+  try {
+    switch (step.type) {
+      case 'goto':
+        return await stepGoto(page, step, baseResult, spec);
+
+      case 'fill':
+        return await stepFill(page, step, baseResult, spec);
+
+      case 'click':
+        return await stepClick(page, step, baseResult, spec);
+
+      case 'expect':
+        return await stepExpect(page, step, baseResult);
+
+      default:
+        baseResult.reason = `Unknown step type: ${step.type}`;
+        baseResult.findingType = 'flow_step_failed';
+        return baseResult;
+    }
+  } catch (err) {
+    baseResult.reason = err.message;
+    baseResult.findingType = 'flow_step_failed';
+    baseResult.evidence = { error: err.toString() };
+    return baseResult;
+  }
+}
+
+async function stepGoto(page, step, result, spec) {
+  const url = new URL(step.url, spec.baseUrl).toString();
+
+  // Check allowlist
+  try {
+    const urlObj = new URL(url);
+    const domainAllowed = spec.allowlist.domains.length === 0 ||
+      spec.allowlist.domains.some(d => urlObj.hostname.includes(d) || urlObj.hostname === d);
+
+    if (!domainAllowed) {
+      result.reason = `Domain ${urlObj.hostname} not in allowlist`;
+      result.findingType = 'unexpected_navigation';
+      result.evidence = { url, allowedDomains: spec.allowlist.domains };
+      return result;
+    }
+
+    const pathAllowed = spec.allowlist.pathsPrefix.length === 0 ||
+      spec.allowlist.pathsPrefix.some(prefix => urlObj.pathname.startsWith(prefix));
+
+    if (!pathAllowed) {
+      result.reason = `Path ${urlObj.pathname} does not match allowlist prefixes`;
+      result.findingType = 'unexpected_navigation';
+      result.evidence = { url, allowedPrefixes: spec.allowlist.pathsPrefix };
+      return result;
+    }
+  } catch (err) {
+    result.reason = `Invalid URL: ${url}`;
+    result.findingType = 'flow_step_failed';
+    result.evidence = { url, error: err.message };
+    return result;
+  }
+
+  await page.goto(url, { waitUntil: 'networkidle' });
+  await waitForSettle(page, { timeoutMs: 3000, settleMs: 500 });
+
+  result.success = true;
+  result.evidence = { url };
+  return result;
+}
+
+async function stepFill(page, step, result, spec) {
+  const selector = step.selector;
+  const resolvedValue = resolveSecrets(step.value, spec.secrets);
+
+  // Check if element exists
+  const element = await page.$(selector);
+  if (!element) {
+    result.reason = `Selector not found: ${selector}`;
+    result.findingType = 'flow_step_failed';
+    result.evidence = { selector };
+    return result;
+  }
+
+  // Fill the field
+  await element.fill(resolvedValue);
+  await waitForSettle(page, { timeoutMs: 2000, settleMs: 300 });
+
+  result.success = true;
+  result.evidence = { selector };
+  // NOTE: resolved value NOT stored in evidence for security
+  return result;
+}
+
+async function stepClick(page, step, result, spec) {
+  const selector = step.selector;
+
+  // Check if element exists
+  const element = await page.$(selector);
+  if (!element) {
+    result.reason = `Selector not found: ${selector}`;
+    result.findingType = 'flow_step_failed';
+    result.evidence = { selector };
+    return result;
+  }
+
+  // Check for deny keywords in element text/aria-label
+  // Use textContent instead of innerText for better compatibility
+  let elementText = await page.evaluate(el => el.textContent || '', element);
+  let elementAriaLabel = '';
+  let elementValue = '';
+
+  try {
+    elementAriaLabel = await element.getAttribute('aria-label') || '';
+  } catch (e) {
+    // Ignore
+  }
+
+  try {
+    elementValue = await element.getAttribute('value') || '';
+  } catch (e) {
+    // Ignore
+  }
+
+  const fullContent = `${elementText} ${elementAriaLabel} ${elementValue}`.toLowerCase();
+
+  for (const keyword of spec.denyKeywords) {
+    if (fullContent.includes(keyword.toLowerCase())) {
+      result.reason = `Click blocked by safety gate: denyKeyword "${keyword}" found in element`;
+      result.findingType = 'blocked_by_safety_gate';
+      result.evidence = { selector, keyword, elementText: '***REDACTED***' };
+      return result;
+    }
+  }
+
+  // Click the element
+  await element.click();
+  await waitForSettle(page, { timeoutMs: 3000, settleMs: 500 });
+
+  result.success = true;
+  result.evidence = { selector };
+  return result;
+}
+
+async function stepExpect(page, step, result) {
+  try {
+    if (step.kind === 'selector') {
+      const element = await page.$(step.selector);
+      if (!element) {
+        result.reason = `Expected selector not found: ${step.selector}`;
+        result.findingType = 'flow_step_failed';
+        result.evidence = { selector: step.selector };
+        return result;
+      }
+      result.success = true;
+      result.evidence = { selector: step.selector };
+      return result;
+    }
+
+    if (step.kind === 'url') {
+      const url = page.url();
+      if (!url.includes(step.prefix)) {
+        result.reason = `Expected URL prefix not found. Current: ${url}, Expected prefix: ${step.prefix}`;
+        result.findingType = 'flow_step_failed';
+        result.evidence = { currentUrl: url, expectedPrefix: step.prefix };
+        return result;
+      }
+      result.success = true;
+      result.evidence = { url, expectedPrefix: step.prefix };
+      return result;
+    }
+
+    if (step.kind === 'route') {
+      const url = new URL(page.url());
+      if (url.pathname !== step.path) {
+        result.reason = `Expected route not matched. Current: ${url.pathname}, Expected: ${step.path}`;
+        result.findingType = 'flow_step_failed';
+        result.evidence = { currentPath: url.pathname, expectedPath: step.path };
+        return result;
+      }
+      result.success = true;
+      result.evidence = { path: url.pathname };
+      return result;
+    }
+  } catch (err) {
+    result.reason = err.message;
+    result.findingType = 'flow_step_failed';
+    result.evidence = { error: err.toString() };
+    return result;
+  }
+
+  result.reason = `Unknown expect kind: ${step.kind}`;
+  result.findingType = 'flow_step_failed';
+  return result;
+}

package/src/verax/flow/flow-spec.js

@@ -0,0 +1,145 @@
+/**
+ * Wave 7 — Flow Specification Parser & Validator
+ *
+ * Validates and normalizes flow spec JSON.
+ * No guessing: explicit selectors, URLs, and step definitions only.
+ */
+
+const ALLOWED_STEP_TYPES = ['goto', 'fill', 'click', 'expect'];
+const ALLOWED_EXPECT_KINDS = ['selector', 'url', 'route'];
+
+/**
+ * Validate and normalize a flow spec.
+ *
+ * @param {Object} spec - Flow spec object
+ * @returns {Object} - Normalized spec
+ * @throws {Error} - On validation failure
+ */
+export function validateFlowSpec(spec) {
+  if (!spec || typeof spec !== 'object') {
+    throw new Error('Flow spec must be a valid JSON object');
+  }
+
+  if (!spec.name || typeof spec.name !== 'string') {
+    throw new Error('Flow spec must have a "name" property');
+  }
+
+  if (!spec.baseUrl || typeof spec.baseUrl !== 'string') {
+    throw new Error('Flow spec must have a "baseUrl" property');
+  }
+
+  if (!Array.isArray(spec.steps) || spec.steps.length === 0) {
+    throw new Error('Flow spec must have a "steps" array with at least one step');
+  }
+
+  // Validate allowlist
+  const allowlist = spec.allowlist || { domains: [], pathsPrefix: ['/'] };
+  if (!Array.isArray(allowlist.domains)) {
+    allowlist.domains = [];
+  }
+  if (!Array.isArray(allowlist.pathsPrefix)) {
+    allowlist.pathsPrefix = ['/'];
+  }
+
+  // Validate denyKeywords
+  const denyKeywords = spec.denyKeywords || [];
+  if (!Array.isArray(denyKeywords)) {
+    throw new Error('denyKeywords must be an array');
+  }
+
+  // Validate steps
+  const steps = spec.steps.map((step, idx) => {
+    if (!step.type || !ALLOWED_STEP_TYPES.includes(step.type)) {
+      throw new Error(`Step ${idx}: type must be one of ${ALLOWED_STEP_TYPES.join(', ')}`);
+    }
+
+    if (step.type === 'goto') {
+      if (!step.url || typeof step.url !== 'string') {
+        throw new Error(`Step ${idx}: goto requires url`);
+      }
+      return step;
+    }
+
+    if (step.type === 'fill') {
+      if (!step.selector || typeof step.selector !== 'string') {
+        throw new Error(`Step ${idx}: fill requires selector`);
+      }
+      if (step.value === undefined) {
+        throw new Error(`Step ${idx}: fill requires value`);
+      }
+      return step;
+    }
+
+    if (step.type === 'click') {
+      if (!step.selector || typeof step.selector !== 'string') {
+        throw new Error(`Step ${idx}: click requires selector`);
+      }
+      return step;
+    }
+
+    if (step.type === 'expect') {
+      if (!step.kind || !ALLOWED_EXPECT_KINDS.includes(step.kind)) {
+        throw new Error(`Step ${idx}: expect requires kind one of ${ALLOWED_EXPECT_KINDS.join(', ')}`);
+      }
+      if (step.kind === 'selector' && !step.selector) {
+        throw new Error(`Step ${idx}: expect selector requires selector`);
+      }
+      if (step.kind === 'url' && !step.prefix) {
+        throw new Error(`Step ${idx}: expect url requires prefix`);
+      }
+      if (step.kind === 'route' && !step.path) {
+        throw new Error(`Step ${idx}: expect route requires path`);
+      }
+      return step;
+    }
+
+    return step;
+  });
+
+  return {
+    name: spec.name,
+    baseUrl: spec.baseUrl,
+    allowlist,
+    denyKeywords,
+    secrets: spec.secrets || {},
+    steps
+  };
+}
+
+/**
+ * Resolve environment variable references like $ENV:VERAX_USER_EMAIL.
+ * Returns actual value or throws if not found.
+ *
+ * @param {string} value - String containing $ENV:VARNAME references
+ * @param {Object} secrets - Map of secret keys to env var names
+ * @returns {string} - Resolved value
+ */
+export function resolveSecrets(value, secrets = {}) {
+  if (typeof value !== 'string') return value;
+
+  // Replace $ENV:VARNAME with actual env var value
+  return value.replace(/\$ENV:([A-Z_][A-Z0-9_]*)/g, (match, varName) => {
+    const envValue = process.env[varName];
+    if (!envValue) {
+      throw new Error(`Environment variable not found: ${varName}`);
+    }
+    return envValue;
+  });
+}
+
+/**
+ * Extract all secret values from a resolved context for redaction.
+ *
+ * @param {Object} secrets - Map of secret keys to env var names
+ * @returns {Set} - Set of actual secret values to redact
+ */
+export function extractSecretValues(secrets = {}) {
+  const values = new Set();
+  for (const envVar of Object.values(secrets)) {
+    const value = process.env[envVar];
+    if (value) {
+      values.add(value);
+    }
+  }
+  return values;
+}

package/src/verax/flow/redaction.js

@@ -0,0 +1,74 @@
+/**
+ * Wave 7 — Redaction Utility
+ *
+ * Ensures secrets are never exposed in artifacts, logs, or traces.
+ * Replaces resolved secret values with "***REDACTED***".
+ */
+
+/**
+ * Redact secrets from a string.
+ *
+ * @param {string} str - Input string
+ * @param {Set} secretValues - Set of actual secret values to replace
+ * @returns {string} - Redacted string
+ */
+export function redactString(str, secretValues = new Set()) {
+  if (typeof str !== 'string' || secretValues.size === 0) {
+    return str;
+  }
+
+  let result = str;
+  for (const secret of secretValues) {
+    if (secret && typeof secret === 'string') {
+      // Use global replace to catch all occurrences
+      const escaped = secret.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      result = result.replace(new RegExp(escaped, 'g'), '***REDACTED***');
+    }
+  }
+  return result;
+}
+
+/**
+ * Redact secrets from a JavaScript object recursively.
+ *
+ * @param {*} obj - Object to redact
+ * @param {Set} secretValues - Set of secret values to replace
+ * @returns {*} - Redacted object (deep copy)
+ */
+export function redactObject(obj, secretValues = new Set()) {
+  if (secretValues.size === 0) {
+    return obj;
+  }
+
+  if (typeof obj === 'string') {
+    return redactString(obj, secretValues);
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => redactObject(item, secretValues));
+  }
+
+  if (obj !== null && typeof obj === 'object') {
+    const redacted = {};
+    for (const [key, value] of Object.entries(obj)) {
+      redacted[key] = redactObject(value, secretValues);
+    }
+    return redacted;
+  }
+
+  return obj;
+}
+
+/**
+ * Redact secrets from JSON string.
+ *
+ * @param {string} jsonStr - JSON string
+ * @param {Set} secretValues - Set of secret values
+ * @returns {string} - Redacted JSON string
+ */
+export function redactJSON(jsonStr, secretValues = new Set()) {
+  if (typeof jsonStr !== 'string' || secretValues.size === 0) {
+    return jsonStr;
+  }
+  return redactString(jsonStr, secretValues);
+}