@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/evidence/evidence-capture-service.js

@@ -0,0 +1,308 @@
+/**
+ * EVIDENCE CAPTURE RELIABILITY LAYER
+ * 
+ * Centralized evidence capture service with retries and failure tracking.
+ * Ensures evidence capture is resilient and failures are never silent.
+ */
+
+import { captureScreenshot } from '../../observe/evidence-capture.js';
+import { captureDomSignature } from '../../observe/dom-signature.js';
+
+/**
+ * Evidence capture failure reason codes (stable)
+ */
+export const EVIDENCE_CAPTURE_FAILURE_CODES = {
+  SCREENSHOT_FAILED: 'EVIDENCE_SCREENSHOT_FAILED',
+  SCREENSHOT_TIMEOUT: 'EVIDENCE_SCREENSHOT_TIMEOUT',
+  DOM_SIGNATURE_FAILED: 'EVIDENCE_DOM_SIGNATURE_FAILED',
+  URL_CAPTURE_FAILED: 'EVIDENCE_URL_CAPTURE_FAILED',
+  UISIGNALS_CAPTURE_FAILED: 'EVIDENCE_UISIGNALS_CAPTURE_FAILED',
+  NETWORK_CAPTURE_FAILED: 'EVIDENCE_NETWORK_CAPTURE_FAILED',
+  UNKNOWN_ERROR: 'EVIDENCE_UNKNOWN_ERROR'
+};
+
+/**
+ * Evidence capture stage codes (stable)
+ */
+export const EVIDENCE_CAPTURE_STAGE = {
+  BEFORE_SCREENSHOT: 'BEFORE_SCREENSHOT',
+  AFTER_SCREENSHOT: 'AFTER_SCREENSHOT',
+  DOM_SIGNATURE: 'DOM_SIGNATURE',
+  URL: 'URL',
+  UISIGNALS: 'UISIGNALS',
+  NETWORK: 'NETWORK'
+};
+
+/**
+ * EvidenceCaptureFailure object (structured failure record)
+ */
+export class EvidenceCaptureFailure {
+  constructor(stage, reasonCode, reason, stackSummary = null, attemptCount = 1) {
+    this.stage = stage;
+    this.reasonCode = reasonCode;
+    this.reason = reason;
+    this.stackSummary = stackSummary || this._extractStackSummary(new Error().stack);
+    this.attemptCount = attemptCount;
+    this.timestamp = new Date().toISOString();
+  }
+
+  _extractStackSummary(stack) {
+    if (!stack) return null;
+    const lines = stack.split('\n').slice(0, 5);
+    return lines.join('\n');
+  }
+
+  toJSON() {
+    return {
+      stage: this.stage,
+      reasonCode: this.reasonCode,
+      reason: this.reason,
+      stackSummary: this.stackSummary,
+      attemptCount: this.attemptCount,
+      timestamp: this.timestamp
+    };
+  }
+}
+
+/**
+ * Screenshot capture with retries
+ * 
+ * @param {Object} page - Playwright page object
+ * @param {string} filepath - Path to save screenshot
+ * @param {Object} options - Options { maxRetries: 2, retryDelayMs: 100 }
+ * @returns {Promise<{ success: boolean, filepath: string | null, failure: EvidenceCaptureFailure | null }>}
+ */
+export async function captureScreenshotWithRetry(page, filepath, options = {}) {
+  const maxRetries = options.maxRetries || 2;
+  const retryDelayMs = options.retryDelayMs || 100;
+  
+  let lastError = null;
+  let attemptCount = 0;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    attemptCount = attempt + 1;
+    try {
+      await captureScreenshot(page, filepath);
+      // Verify file was created
+      const { existsSync } = await import('fs');
+      if (existsSync(filepath)) {
+        return { success: true, filepath, failure: null };
+      }
+      throw new Error('Screenshot file was not created');
+    } catch (error) {
+      lastError = error;
+      
+      // If not last attempt, wait before retry
+      if (attempt < maxRetries) {
+        await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+      }
+    }
+  }
+  
+  // All retries failed
+  const failure = new EvidenceCaptureFailure(
+    filepath.includes('before') ? EVIDENCE_CAPTURE_STAGE.BEFORE_SCREENSHOT : EVIDENCE_CAPTURE_STAGE.AFTER_SCREENSHOT,
+    lastError?.message?.includes('timeout') ? EVIDENCE_CAPTURE_FAILURE_CODES.SCREENSHOT_TIMEOUT : EVIDENCE_CAPTURE_FAILURE_CODES.SCREENSHOT_FAILED,
+    lastError?.message || 'Screenshot capture failed after retries',
+    lastError?.stack,
+    attemptCount
+  );
+  
+  return { success: false, filepath: null, failure };
+}
+
+/**
+ * Capture DOM signature with error handling
+ * 
+ * @param {Object} page - Playwright page object
+ * @returns {Promise<{ success: boolean, domSignature: string | null, failure: EvidenceCaptureFailure | null }>}
+ */
+export async function captureDomSignatureSafe(page) {
+  try {
+    const domSignature = await captureDomSignature(page);
+    // @ts-expect-error - digest returns string
+    return { success: true, domSignature, failure: null };
+  } catch (error) {
+    const failure = new EvidenceCaptureFailure(
+      EVIDENCE_CAPTURE_STAGE.DOM_SIGNATURE,
+      EVIDENCE_CAPTURE_FAILURE_CODES.DOM_SIGNATURE_FAILED,
+      error.message || 'DOM signature capture failed',
+      error.stack
+    );
+    return { success: false, domSignature: null, failure };
+  }
+}
+
+/**
+ * Capture URL with error handling
+ * 
+ * @param {Object} page - Playwright page object
+ * @returns {Promise<{ success: boolean, url: string | null, failure: EvidenceCaptureFailure | null }>}
+ */
+export async function captureUrlSafe(page) {
+  try {
+    const url = page.url();
+    return { success: true, url, failure: null };
+  } catch (error) {
+    const failure = new EvidenceCaptureFailure(
+      EVIDENCE_CAPTURE_STAGE.URL,
+      EVIDENCE_CAPTURE_FAILURE_CODES.URL_CAPTURE_FAILED,
+      error.message || 'URL capture failed',
+      error.stack
+    );
+    return { success: false, url: null, failure };
+  }
+}
+
+/**
+ * Capture UI signals snapshot with error handling
+ * 
+ * @param {Object} uiSignalSensor - UISignalSensor instance
+ * @param {Object} page - Playwright page object
+ * @param {number} interactionTime - Optional interaction timestamp
+ * @param {Object} beforeSnapshot - Optional before snapshot
+ * @returns {Promise<{ success: boolean, uiSignals: Object | null, failure: EvidenceCaptureFailure | null }>}
+ */
+export async function captureUiSignalsSafe(uiSignalSensor, page, interactionTime = null, beforeSnapshot = null) {
+  try {
+    const uiSignals = await uiSignalSensor.snapshot(page, interactionTime, beforeSnapshot);
+    return { success: true, uiSignals, failure: null };
+  } catch (error) {
+    const failure = new EvidenceCaptureFailure(
+      EVIDENCE_CAPTURE_STAGE.UISIGNALS,
+      EVIDENCE_CAPTURE_FAILURE_CODES.UISIGNALS_CAPTURE_FAILED,
+      error.message || 'UI signals capture failed',
+      error.stack
+    );
+    return { success: false, uiSignals: null, failure };
+  }
+}
+
+/**
+ * Capture network snapshot with error handling
+ * 
+ * @param {Object} networkSensor - NetworkSensor instance
+ * @param {string} windowId - Network window ID
+ * @returns {Promise<{ success: boolean, networkSummary: Object | null, failure: EvidenceCaptureFailure | null }>}
+ */
+export async function captureNetworkSafe(networkSensor, windowId) {
+  try {
+    const networkSummary = networkSensor.stopWindow(windowId);
+    return { success: true, networkSummary, failure: null };
+  } catch (error) {
+    const failure = new EvidenceCaptureFailure(
+      EVIDENCE_CAPTURE_STAGE.NETWORK,
+      EVIDENCE_CAPTURE_FAILURE_CODES.NETWORK_CAPTURE_FAILED,
+      error.message || 'Network capture failed',
+      error.stack
+    );
+    return { success: false, networkSummary: null, failure };
+  }
+}
+
+/**
+ * Comprehensive evidence capture for a finding
+ * 
+ * @param {Object} params - Capture parameters
+ * @param {Object} params.page - Playwright page object
+ * @param {string} params.beforeScreenshotPath - Before screenshot path
+ * @param {string} params.afterScreenshotPath - After screenshot path
+ * @param {Object} params.uiSignalSensor - UISignalSensor instance
+ * @param {Object} params.networkSensor - NetworkSensor instance
+ * @param {string} params.networkWindowId - Network window ID
+ * @param {number} params.interactionTime - Interaction timestamp
+ * @param {Object} params.beforeSnapshot - Before snapshot
+ * @returns {Promise<{ evidence: Object, failures: Array<EvidenceCaptureFailure> }>}
+ */
+export async function captureEvidenceComprehensive(params) {
+  const {
+    page,
+    beforeScreenshotPath,
+    afterScreenshotPath,
+    uiSignalSensor,
+    networkSensor,
+    networkWindowId,
+    interactionTime,
+    beforeSnapshot
+  } = params;
+  
+  const failures = [];
+  const evidence = {
+    before: {},
+    after: {},
+    signals: {}
+  };
+  
+  // Capture before screenshot
+  if (beforeScreenshotPath) {
+    const beforeScreenshot = await captureScreenshotWithRetry(page, beforeScreenshotPath);
+    if (beforeScreenshot.success) {
+      evidence.before.screenshot = beforeScreenshotPath;
+    } else {
+      failures.push(beforeScreenshot.failure);
+    }
+  }
+  
+  // Capture after screenshot
+  if (afterScreenshotPath) {
+    const afterScreenshot = await captureScreenshotWithRetry(page, afterScreenshotPath);
+    if (afterScreenshot.success) {
+      evidence.after.screenshot = afterScreenshotPath;
+    } else {
+      failures.push(afterScreenshot.failure);
+    }
+  }
+  
+  // Capture URLs
+  const beforeUrl = await captureUrlSafe(page);
+  if (beforeUrl.success) {
+    evidence.before.url = beforeUrl.url;
+  } else {
+    failures.push(beforeUrl.failure);
+  }
+  
+  const afterUrl = await captureUrlSafe(page);
+  if (afterUrl.success) {
+    evidence.after.url = afterUrl.url;
+  } else {
+    failures.push(afterUrl.failure);
+  }
+  
+  // Capture DOM signatures
+  const beforeDom = await captureDomSignatureSafe(page);
+  if (beforeDom.success) {
+    evidence.before.domSignature = beforeDom.domSignature;
+  } else {
+    failures.push(beforeDom.failure);
+  }
+  
+  const afterDom = await captureDomSignatureSafe(page);
+  if (afterDom.success) {
+    evidence.after.domSignature = afterDom.domSignature;
+  } else {
+    failures.push(afterDom.failure);
+  }
+  
+  // Capture UI signals
+  if (uiSignalSensor) {
+    const uiSignals = await captureUiSignalsSafe(uiSignalSensor, page, interactionTime, beforeSnapshot);
+    if (uiSignals.success) {
+      evidence.signals.uiSignals = uiSignals.uiSignals;
+    } else {
+      failures.push(uiSignals.failure);
+    }
+  }
+  
+  // Capture network
+  if (networkSensor && networkWindowId) {
+    const network = await captureNetworkSafe(networkSensor, networkWindowId);
+    if (network.success) {
+      evidence.signals.network = network.networkSummary;
+    } else {
+      failures.push(network.failure);
+    }
+  }
+  
+  return { evidence, failures };
+}
+

package/src/verax/core/evidence/evidence-intent-ledger.js

@@ -0,0 +1,166 @@
+/**
+ * EVIDENCE INTENT LEDGER
+ * 
+ * Audit trail of evidence capture attempts per finding.
+ * Records what evidence was required, what was captured, and what failed.
+ * This is NOT proof; it is an audit trail proving we attempted to capture evidence.
+ */
+
+import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { EVIDENCE_CAPTURE_STAGE, EVIDENCE_CAPTURE_FAILURE_CODES as _EVIDENCE_CAPTURE_FAILURE_CODES } from './evidence-capture-service.js';
+
+/**
+ * Required evidence fields for CONFIRMED findings (stable)
+ */
+export const REQUIRED_EVIDENCE_FIELDS = [
+  'trigger.source',
+  'before.screenshot',
+  'after.screenshot',
+  'before.url',
+  'after.url',
+  'action.interaction',
+  'signals.network',
+  'signals.uiSignals'
+];
+
+/**
+ * Build evidence intent entry for a finding
+ * 
+ * @param {Object} finding - Finding object
+ * @param {Object} evidencePackage - Evidence package
+ * @param {Array<Object>} captureFailures - Array of EvidenceCaptureFailure objects
+ * @returns {Object} Evidence intent entry
+ */
+export function buildEvidenceIntentEntry(finding, evidencePackage, captureFailures = []) {
+  const findingIdentity = finding.findingId || finding.id || `finding-${Date.now()}`;
+  
+  // Determine required fields based on finding severity
+  const requiredFields = finding.severity === 'CONFIRMED' || finding.status === 'CONFIRMED' 
+    ? REQUIRED_EVIDENCE_FIELDS 
+    : [];
+  
+  // Check capture outcomes for each required field
+  const captureOutcomes = {};
+  const missingFields = [];
+  
+  for (const field of requiredFields) {
+    const [section, key] = field.split('.');
+    
+    let captured = false;
+    let failure = null;
+    
+    // Check if field exists in evidence package
+    if (section === 'trigger' && evidencePackage.trigger?.[key]) {
+      captured = true;
+    } else if (section === 'before' && evidencePackage.before?.[key]) {
+      captured = true;
+    } else if (section === 'after' && evidencePackage.after?.[key]) {
+      captured = true;
+    } else if (section === 'action' && evidencePackage.action?.[key]) {
+      captured = true;
+    } else if (section === 'signals' && evidencePackage.signals?.[key]) {
+      captured = true;
+    }
+    
+    // Check if there was a capture failure for this field
+    if (!captured) {
+      const fieldFailure = captureFailures.find(f => {
+        if (field.includes('screenshot') && f.stage.includes('SCREENSHOT')) return true;
+        if (field.includes('domSignature') && f.stage === EVIDENCE_CAPTURE_STAGE.DOM_SIGNATURE) return true;
+        if (field.includes('url') && f.stage === EVIDENCE_CAPTURE_STAGE.URL) return true;
+        if (field.includes('uiSignals') && f.stage === EVIDENCE_CAPTURE_STAGE.UISIGNALS) return true;
+        if (field.includes('network') && f.stage === EVIDENCE_CAPTURE_STAGE.NETWORK) return true;
+        return false;
+      });
+      
+      if (fieldFailure) {
+        failure = {
+          stage: fieldFailure.stage,
+          reasonCode: fieldFailure.reasonCode,
+          reason: fieldFailure.reason
+        };
+      }
+      
+      missingFields.push(field);
+    }
+    
+    captureOutcomes[field] = {
+      required: true,
+      captured,
+      failure
+    };
+  }
+  
+  return {
+    findingIdentity,
+    findingType: finding.type || 'finding',
+    severity: finding.severity || finding.status || 'SUSPECTED',
+    requiredFields,
+    captureOutcomes,
+    missingFields,
+    evidencePackageComplete: evidencePackage.isComplete === true,
+    timestamp: new Date().toISOString()
+  };
+}
+
+/**
+ * Write evidence intent ledger
+ * 
+ * @param {string} runDir - Run directory
+ * @param {Array<Object>} findings - Array of findings with evidence packages
+ * @param {Map<string, Array<Object>>} captureFailuresMap - Map of findingId -> capture failures
+ * @returns {string} Path to written evidence.intent.json
+ */
+export function writeEvidenceIntentLedger(runDir, findings, captureFailuresMap = new Map()) {
+  const intentPath = resolve(runDir, 'evidence.intent.json');
+  
+  // Build intent entries (deterministic ordering by findingIdentity)
+  const entries = [];
+  
+  for (const finding of findings || []) {
+    const findingIdentity = finding.findingId || finding.id || `finding-${findings.indexOf(finding)}`;
+    const captureFailures = captureFailuresMap.get(findingIdentity) || [];
+    const evidencePackage = finding.evidencePackage || {};
+    
+    const entry = buildEvidenceIntentEntry(finding, evidencePackage, captureFailures);
+    entries.push(entry);
+  }
+  
+  // Sort by findingIdentity for deterministic ordering
+  entries.sort((a, b) => a.findingIdentity.localeCompare(b.findingIdentity));
+  
+  const ledger = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    totalFindings: entries.length,
+    entries
+  };
+  
+  writeFileSync(intentPath, JSON.stringify(ledger, null, 2) + '\n');
+  
+  return intentPath;
+}
+
+/**
+ * Read evidence intent ledger
+ * 
+ * @param {string} runDir - Run directory
+ * @returns {Object | null} Evidence intent ledger or null if not found
+ */
+export function readEvidenceIntentLedger(runDir) {
+  const intentPath = resolve(runDir, 'evidence.intent.json');
+  
+  if (!existsSync(intentPath)) {
+    return null;
+  }
+  
+  try {
+    const content = readFileSync(intentPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+    return JSON.parse(content);
+  } catch (error) {
+    return null;
+  }
+}
+