@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/core/product-definition.js

@@ -0,0 +1,127 @@
+/**
+ * VERAX Product Definition - Locked in Code
+ * 
+ * Single source of truth for what VERAX is, does, and doesn't do.
+ * This definition is wired into CLI help, documentation, and assertions throughout the codebase.
+ * 
+ * CRITICAL: This is not marketing copy. This is the operational contract.
+ */
+
+export const VERAX_PRODUCT_DEFINITION = {
+  // What VERAX is: one-liner
+  oneLiner: 'A forensic observation engine that detects silent user failures by comparing what your code promises with what users can actually observe.',
+
+  // Does: explicit capabilities
+  does: [
+    'Observes real websites in real browsers using Playwright',
+    'Reads source code to extract explicit expectations (navigation, network calls, state changes)',
+    'Compares code-derived expectations with observed browser behavior',
+    'Reports gaps between promise and reality with concrete evidence',
+    'Assigns confidence levels (HIGH/MEDIUM/LOW) based on evidence strength',
+    'Runs locally on developer machines or in CI/CD pipelines',
+    'Produces forensic artifacts: findings, traces, screenshots, network logs',
+    'Requires and validates source code as the source of truth for expectations',
+    'Enforces Evidence Law: findings cannot be CONFIRMED without sufficient evidence'
+  ],
+
+  // Does NOT: explicit limitations
+  doesNot: [
+    'Guess intent - only analyzes explicit code promises',
+    'Detect dynamic routes (e.g., /user/${id}) - skipped intentionally',
+    'Replace QA or automated tests - complements them',
+    'Monitor production traffic',
+    'Support every framework - only documented frameworks (React, Next.js, Vue, static HTML)',
+    'Detect every bug - only gaps backed by explicit code promises',
+    'Operate as a hosted or public-website scanner - runs locally with your repository',
+    'Run without source code - requires local access to codebase',
+    'Create CONFIRMED findings without evidence - Evidence Law is mandatory'
+  ],
+
+  // Success conditions: when does a VERAX run succeed?
+  successConditions: [
+    'Run executes without crashing',
+    'At least one expectation is extracted from source code',
+    'At least one interaction is discovered in the browser',
+    'Findings are generated from expectations vs observations',
+    'All findings satisfy contracts (have evidence, confidence, signals)',
+    'All CONFIRMED findings have substantive evidence (per Evidence Law)',
+    'Artifacts are written to standard locations (.verax/runs/<runId>/)'
+  ],
+
+  // Failure conditions: when does a VERAX run fail?
+  failureConditions: [
+    'No source code found or readable',
+    'No expectations extracted from source code',
+    'URL is unreachable or site fails to load',
+    'No interactions discovered in the browser',
+    'Critical invariants violated (e.g., findings with missing required fields)',
+    'A CONFIRMED finding violates Evidence Law (has insufficient evidence)'
+  ],
+
+  // The Evidence Law: most critical rule
+  evidenceLaw: {
+    statement: 'A finding cannot be marked CONFIRMED without sufficient evidence.',
+    definition: 'Substantive evidence means at least one of: DOM changes, URL changes, network requests, state mutations, or concrete sensor data.',
+    enforcement: 'If a finding is marked CONFIRMED but lacks evidence, it must be downgraded to SUSPECTED or dropped.',
+    rationale: 'VERAX exists to surface real gaps backed by observable signals. Unsubstantiated claims are guesses, not forensic findings.'
+  },
+
+  // Local source code requirement
+  sourceCodeRequirement: {
+    statement: 'VERAX requires local access to source code. It is not a public website scanner.',
+    rationale: 'Expectations are extracted through static analysis of source files. Without code, VERAX cannot work.',
+    implication: 'VERAX is designed for developers in their repositories, not for third-party auditing of closed-source applications.'
+  },
+
+  // Version: for tracking breaking changes
+  schemaVersion: 1
+};
+
+/**
+ * Format product definition for CLI display
+ */
+export function formatProductDefinitionForCLI() {
+  const def = VERAX_PRODUCT_DEFINITION;
+  const lines = [];
+
+  lines.push('');
+  lines.push('═══════════════════════════════════════════════════════════════');
+  lines.push('VERAX PRODUCT DEFINITION');
+  lines.push('═══════════════════════════════════════════════════════════════');
+  lines.push('');
+  lines.push(`What: ${def.oneLiner}`);
+  lines.push('');
+  lines.push('Does:');
+  def.does.forEach(item => lines.push(`  • ${item}`));
+  lines.push('');
+  lines.push('Does NOT:');
+  def.doesNot.forEach(item => lines.push(`  • ${item}`));
+  lines.push('');
+  lines.push('EVIDENCE LAW (Mandatory):');
+  lines.push(`  "${def.evidenceLaw.statement}"`);
+  lines.push(`  Substantive evidence = DOM/URL/network/state changes or sensor data`);
+  lines.push(`  Enforcement: CONFIRMED findings must have evidence, else downgraded to SUSPECTED`);
+  lines.push('');
+  lines.push('SOURCE CODE REQUIREMENT (Mandatory):');
+  lines.push(`  "${def.sourceCodeRequirement.statement}"`);
+  lines.push('');
+  lines.push('═══════════════════════════════════════════════════════════════');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// Consistent banner for all user-facing surfaces
+export function getSourceCodeRequirementBanner() {
+  return 'VERAX requires local access to source code. It is not a public website scanner.';
+}
+
+/**
+ * Format just the Evidence Law for inline display
+ */
+export function formatEvidenceLawForDisplay() {
+  const law = VERAX_PRODUCT_DEFINITION.evidenceLaw;
+  return `\n** EVIDENCE LAW: ${law.statement} **\n   Substantive evidence = DOM/URL/network/state changes.\n   CONFIRMED findings without evidence are downgraded to SUSPECTED.\n`;
+}
+
+export default VERAX_PRODUCT_DEFINITION;

package/src/verax/core/release/provenance.builder.js

@@ -0,0 +1,271 @@
+/**
+ * PHASE 21.7 — Release Provenance Builder
+ * 
+ * Generates release.provenance.json with complete build metadata.
+ * Dirty repo = BLOCKING.
+ */
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { createHash } from 'crypto';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get git commit hash
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {string|null} Commit hash or null
+ */
+function getGitCommit(projectDir) {
+  try {
+    const result = execSync('git rev-parse HEAD', { 
+      cwd: projectDir,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return result.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if git repo is dirty
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {boolean} True if dirty
+ */
+function isGitDirty(projectDir) {
+  try {
+    const result = execSync('git status --porcelain', { 
+      cwd: projectDir,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return result.trim().length > 0;
+  } catch {
+    // If not a git repo, consider it dirty
+    return true;
+  }
+}
+
+/**
+ * Get package version
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {string|null} Version or null
+ */
+function getPackageVersion(projectDir) {
+  try {
+    const pkgPath = resolve(projectDir, 'package.json');
+    if (!existsSync(pkgPath)) {
+      return null;
+    }
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get environment info
+ * 
+ * @returns {Object} Environment info
+ */
+function getEnvironmentInfo() {
+  return {
+    node: process.version,
+    os: process.platform,
+    arch: process.arch
+  };
+}
+
+/**
+ * Compute hash of a file
+ * 
+ * @param {string} filePath - File path
+ * @returns {string|null} SHA256 hash or null
+ */
+function hashFile(filePath) {
+  try {
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get policy hash
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} policyName - Policy name (guardrails or confidence)
+ * @returns {Promise<string|null>} Policy hash or null
+ */
+async function getPolicyHash(projectDir, policyName) {
+  try {
+    // Try to load the policy
+    if (policyName === 'guardrails') {
+      const { loadGuardrailsPolicy } = await import('../guardrails/policy.loader.js');
+      const policy = loadGuardrailsPolicy(null, projectDir);
+      const policyStr = JSON.stringify(policy, null, 0);
+      return createHash('sha256').update(policyStr).digest('hex');
+    } else if (policyName === 'confidence') {
+      const { loadConfidencePolicy } = await import('../confidence/confidence.loader.js');
+      const policy = loadConfidencePolicy(null, projectDir);
+      const policyStr = JSON.stringify(policy, null, 0);
+      return createHash('sha256').update(policyStr).digest('hex');
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get artifact hashes
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {Object} Artifact hashes
+ */
+function getArtifactHashes(projectDir) {
+  const distPath = resolve(projectDir, 'dist');
+  const cliPath = resolve(projectDir, 'bin', 'verax.js');
+  
+  return {
+    dist: existsSync(distPath) ? hashFile(resolve(distPath, 'index.js')) : null,
+    cli: hashFile(cliPath)
+  };
+}
+
+/**
+ * Get schema version from artifacts
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {string|null} Schema version or null
+ */
+function getSchemaVersion(projectDir) {
+  try {
+    // Check for artifact registry
+    const registryPath = resolve(projectDir, 'src', 'verax', 'core', 'artifacts', 'registry.js');
+    if (existsSync(registryPath)) {
+      const content = readFileSync(registryPath, 'utf-8');
+      // Try to extract schema version from registry
+      const match = content.match(/SCHEMA_VERSION\s*[:=]\s*['"]([^'"]+)['"]/);
+      if (match) {
+        return match[1];
+      }
+    }
+    return '1.0.0'; // Default
+  } catch {
+    return '1.0.0';
+  }
+}
+
+/**
+ * Check GA status
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {Promise<string>} GA status (GA-READY, GA-BLOCKED, UNKNOWN)
+ */
+async function getGAStatus(projectDir) {
+  try {
+    const { findLatestRunId } = await import('../../../cli/util/run-resolver.js');
+    const runId = findLatestRunId(projectDir);
+    if (!runId) {
+      return 'UNKNOWN';
+    }
+    
+    const { checkGAStatus } = await import('../ga/ga.enforcer.js');
+    const check = checkGAStatus(projectDir, runId);
+    
+    if (check.ready) {
+      return 'GA-READY';
+    } else {
+      return 'GA-BLOCKED';
+    }
+  } catch {
+    return 'UNKNOWN';
+  }
+}
+
+/**
+ * Build release provenance
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {Promise<Object>} Provenance object
+ * @throws {Error} If repo is dirty
+ */
+export async function buildProvenance(projectDir) {
+  const gitCommit = getGitCommit(projectDir);
+  const gitDirty = isGitDirty(projectDir);
+  
+  // HARD LOCK: Dirty repo = BLOCKING
+  if (gitDirty) {
+    throw new Error('Cannot build provenance: Git repository is dirty. Commit all changes first.');
+  }
+  
+  const version = getPackageVersion(projectDir);
+  const env = getEnvironmentInfo();
+  
+  // Get policy hashes
+  const guardrailsHash = await getPolicyHash(projectDir, 'guardrails');
+  const confidenceHash = await getPolicyHash(projectDir, 'confidence');
+  
+  const gaStatus = await getGAStatus(projectDir);
+  const schemaVersion = getSchemaVersion(projectDir);
+  const hashes = getArtifactHashes(projectDir);
+  
+  const provenance = {
+    version: version || 'unknown',
+    git: {
+      commit: gitCommit || 'unknown',
+      dirty: false
+    },
+    env: {
+      node: env.node,
+      os: env.os,
+      arch: env.arch
+    },
+    policies: {
+      guardrails: guardrailsHash || 'unknown',
+      confidence: confidenceHash || 'unknown'
+    },
+    gaStatus: gaStatus,
+    artifacts: {
+      schemaVersion: schemaVersion
+    },
+    hashes: hashes,
+    builtAt: new Date().toISOString()
+  };
+  
+  return provenance;
+}
+
+/**
+ * Write provenance to file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {Object} provenance - Provenance object
+ * @returns {string} Path to written file
+ */
+export function writeProvenance(projectDir, provenance) {
+  const outputDir = resolve(projectDir, 'release');
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  
+  const outputPath = resolve(outputDir, 'release.provenance.json');
+  writeFileSync(outputPath, JSON.stringify(provenance, null, 2), 'utf-8');
+  
+  return outputPath;
+}
+

package/src/verax/core/release/release-report-writer.js

@@ -0,0 +1,40 @@
+/**
+ * ENTERPRISE READINESS — Release Report Writer
+ * 
+ * Writes release.report.json artifact with release readiness check results.
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Write release report
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {Object} releaseStatus - Release readiness status
+ * @returns {string} Path to written file
+ */
+export function writeReleaseReport(projectDir, releaseStatus) {
+  const outputDir = resolve(projectDir, 'release');
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  
+  const reportPath = resolve(outputDir, 'release.report.json');
+  
+  const report = {
+    contractVersion: 1,
+    generatedAt: new Date().toISOString(),
+    releaseReady: releaseStatus.releaseReady || false,
+    status: releaseStatus.status || {},
+    summary: releaseStatus.summary || {},
+    failureCodes: Object.entries(releaseStatus.status || {})
+      .filter(([_, s]) => !s.ok)
+      .flatMap(([key, s]) => s.blockers?.map(b => `${key.toUpperCase()}_${b.code || 'BLOCKED'}`) || [])
+  };
+  
+  writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf-8');
+  
+  return reportPath;
+}
+

package/src/verax/core/release/release.enforcer.js

@@ -0,0 +1,159 @@
+/**
+ * PHASE 21.7 — Release Enforcer
+ * 
+ * Hard lock: blocks publish/release without GA-READY + Provenance + SBOM + Reproducible.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { checkGAStatus } from '../ga/ga.enforcer.js';
+import { findLatestRunId } from '../../../cli/util/run-resolver.js';
+import { createInternalFailure } from '../failures/failure.factory.js';
+import { FAILURE_CODE } from '../failures/failure.types.js';
+import { isBaselineFrozen, enforceBaseline } from '../baseline/baseline.enforcer.js';
+import { FailureLedger } from '../failures/failure.ledger.js';
+
+/**
+ * Check if release is allowed
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} operation - Operation name (publish, release, tag)
+ * @throws {Error} If release is blocked
+ */
+export async function enforceReleaseReadiness(projectDir, operation = 'release') {
+  const blockers = [];
+  
+  // 1. Check GA status
+  try {
+    const runId = findLatestRunId(projectDir);
+    if (!runId) {
+      blockers.push('No runs found. Run a scan and verify GA readiness first.');
+    } else {
+      const gaCheck = checkGAStatus(projectDir, runId);
+      if (!gaCheck.ready) {
+        const blockerMessages = gaCheck.status?.blockers?.map(b => b.message).join('; ') || 'GA not ready';
+        blockers.push(`GA-BLOCKED: ${blockerMessages}`);
+      }
+    }
+  } catch (error) {
+    blockers.push(`GA check failed: ${error.message}`);
+  }
+  
+  // 2. Check Provenance
+  const provenancePath = resolve(projectDir, 'release', 'release.provenance.json');
+  if (!existsSync(provenancePath)) {
+    blockers.push('Provenance not found. Run "verax release:check" first.');
+  } else {
+    try {
+      const provenance = JSON.parse(readFileSync(provenancePath, 'utf-8'));
+      if (provenance.git?.dirty) {
+        blockers.push('Provenance indicates dirty git repository');
+      }
+      if (provenance.gaStatus !== 'GA-READY') {
+        blockers.push(`Provenance GA status is ${provenance.gaStatus}, not GA-READY`);
+      }
+    } catch (error) {
+      blockers.push(`Invalid provenance: ${error.message}`);
+    }
+  }
+  
+  // 3. Check SBOM
+  const sbomPath = resolve(projectDir, 'release', 'sbom.json');
+  if (!existsSync(sbomPath)) {
+    blockers.push('SBOM not found. Run "verax release:check" first.');
+  } else {
+    try {
+      const sbom = JSON.parse(readFileSync(sbomPath, 'utf-8'));
+      if (!sbom.bomFormat || !sbom.components || !Array.isArray(sbom.components) || sbom.components.length === 0) {
+        blockers.push('Invalid or empty SBOM');
+      }
+    } catch (error) {
+      blockers.push(`Invalid SBOM: ${error.message}`);
+    }
+  }
+  
+  // 4. Check Reproducibility
+  const reproducibilityPath = resolve(projectDir, 'release', 'reproducibility.report.json');
+  if (!existsSync(reproducibilityPath)) {
+    blockers.push('Reproducibility report not found. Run "verax release:check" first.');
+  } else {
+    try {
+      const report = JSON.parse(readFileSync(reproducibilityPath, 'utf-8'));
+      if (report.verdict !== 'REPRODUCIBLE') {
+        const differences = report.differences?.map(d => d.message).join('; ') || 'Build is not reproducible';
+        blockers.push(`NON_REPRODUCIBLE: ${differences}`);
+      }
+    } catch (error) {
+      blockers.push(`Invalid reproducibility report: ${error.message}`);
+    }
+  }
+  
+  // 5. Check Security (PHASE 21.8)
+  const secretsPath = resolve(projectDir, 'release', 'security.secrets.report.json');
+  const vulnPath = resolve(projectDir, 'release', 'security.vuln.report.json');
+  const supplyChainPath = resolve(projectDir, 'release', 'security.supplychain.report.json');
+  
+  if (!existsSync(secretsPath) || !existsSync(vulnPath) || !existsSync(supplyChainPath)) {
+    blockers.push('Security reports not found. Run "verax security:check" first.');
+  } else {
+    try {
+      // Check secrets
+      const secretsReport = JSON.parse(readFileSync(secretsPath, 'utf-8'));
+      if (secretsReport.hasSecrets) {
+        blockers.push(`SECURITY-BLOCKED: Secrets detected (${secretsReport.summary.total} finding(s))`);
+      }
+      
+      // Check vulnerabilities
+      const vulnReport = JSON.parse(readFileSync(vulnPath, 'utf-8'));
+      if (vulnReport.blocking) {
+        blockers.push(`SECURITY-BLOCKED: Critical/High vulnerabilities detected (${vulnReport.summary.critical + vulnReport.summary.high} total)`);
+      }
+      
+      // Check supply-chain
+      const supplyChainReport = JSON.parse(readFileSync(supplyChainPath, 'utf-8'));
+      if (!supplyChainReport.ok) {
+        blockers.push(`SECURITY-BLOCKED: Supply-chain violations (${supplyChainReport.summary.totalViolations} violation(s))`);
+      }
+    } catch (error) {
+      blockers.push(`Security check failed: ${error.message}`);
+    }
+  }
+  
+  // 6. Check Performance (PHASE 21.9) - BLOCKING perf violations block release
+  const runId = findLatestRunId(projectDir);
+  if (runId) {
+    try {
+      const { checkPerformanceStatus } = await import('../perf/perf.enforcer.js');
+      const perfCheck = checkPerformanceStatus(projectDir, runId);
+      
+      if (perfCheck.exists && !perfCheck.ok) {
+        blockers.push(`PERFORMANCE-BLOCKED: ${perfCheck.blockers.join('; ')}`);
+      }
+    } catch (error) {
+      // Performance check failure is not a blocker (may be from old runs)
+    }
+  }
+  
+  // 7. Baseline Freeze Enforcement (PHASE 21.11)
+  // After GA, baseline must be frozen and unchanged
+  if (isBaselineFrozen(projectDir)) {
+    const failureLedger = new FailureLedger(projectDir, runId || 'unknown');
+    const baselineCheck = enforceBaseline(projectDir, failureLedger);
+    if (baselineCheck.blocked) {
+      blockers.push(`BASELINE-DRIFT: ${baselineCheck.message}. Changes to core contracts/policies after GA require MAJOR version bump and baseline regeneration.`);
+    }
+  }
+  
+  // If any blockers, throw error
+  if (blockers.length > 0) {
+    const failure = createInternalFailure(
+      FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+      `Cannot ${operation}: RELEASE-BLOCKED. ${blockers.join('; ')}`,
+      'release.enforcer',
+      { operation, blockers },
+      null
+    );
+    throw failure;
+  }
+}
+