@odavl/guardian 0.1.0-rc1 → 1.0.0

package/config/README.md

@@ -0,0 +1,59 @@
+# Guardian Configuration
+
+This directory contains all Guardian configuration files.
+
+## Structure
+
+```
+config/
+├── guardian.config.json    # Main Guardian configuration
+├── guardian.policy.json    # Testing policy and failure thresholds
+└── profiles/               # Pre-configured profiles for different use cases
+    ├── docs.yaml           # Documentation site profile
+    ├── ecommerce.yaml      # E-commerce/Shop profile
+    ├── landing-demo.yaml   # Landing page profile
+    ├── marketing.yaml      # Marketing site profile
+    └── saas.yaml           # SaaS application profile
+```
+
+## Files
+
+### guardian.config.json
+Main configuration file that controls:
+- Base URL for testing
+- Test mode (SAFE/NORMAL)
+- Page crawling limits (maxPages, maxDepth)
+- Performance thresholds
+- Safety rules (URL patterns, selectors to avoid)
+- Artifact output directory
+
+### guardian.policy.json
+Defines testing policies:
+- Failure severity thresholds
+- Maximum allowed warnings/errors
+- Regression detection settings
+- Baseline requirements
+
+### Profiles (profiles/*.yaml)
+Pre-configured profiles for specific website types:
+- **docs.yaml**: For documentation sites (40 pages, 5 depth)
+- **ecommerce.yaml**: For e-commerce (35 pages, 4 depth, with revenue tracking)
+- **landing-demo.yaml**: For landing pages (20 pages, 2 depth)
+- **marketing.yaml**: For marketing sites (20 pages, 3 depth)
+- **saas.yaml**: For SaaS apps (25 pages, 3 depth, with auth)
+
+## Usage
+
+Guardian automatically discovers these files in the following order:
+1. `config/guardian.policy.json` (preferred)
+2. `guardian.policy.json` (legacy)
+3. `.odavl-guardian/guardian.policy.json` (CI/CD)
+
+## Customization
+
+Edit these files to:
+- Adjust safety rules and URL patterns
+- Change policy severity thresholds
+- Modify performance baselines
+- Configure auth requirements
+- Set revenue tracking paths

package/config/profiles/landing-demo.yaml

@@ -0,0 +1,16 @@
+# Guardian profile template: Landing/Demo
+baseUrl: https://example.com
+profile: landing-demo
+mode: SAFE
+maxPages: 20
+maxDepth: 2
+slowThresholdMs: 8000
+traceEnabled: false
+harEnabled: false
+auth:
+  enabled: false
+revenue:
+  enabled: false
+regression:
+  enabled: false
+policyPack: landing-demo

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@odavl/guardian",
-  "version": "0.1.0-rc1",
+  "version": "1.0.0",
   "description": "ODAVL Guardian — Market Reality Testing Engine with Visual Diffs, Behavioral Signals, Auto-Discovery, Intelligence, and CI/CD Integration",
   "license": "MIT",
   "author": "ODAVL",
   "repository": {
     "type": "git",
-    "url": "https://github.com/odavlstudio/odavlguardian"
+    "url": "git+https://github.com/odavlstudio/odavlguardian.git"
   },
   "keywords": [
     "testing",
@@ -24,24 +24,27 @@
   "bin": {
     "guardian": "bin/guardian.js"
   },
+  "main": "src/guardian/index.js",
   "files": [
     "bin/",
     "src/",
     "flows/",
     "policies/",
-    "guardian.config.json",
-    "guardian.policy.json",
-    "guardian.profile.docs.yaml",
-    "guardian.profile.ecommerce.yaml",
-    "guardian.profile.marketing.yaml",
-    "guardian.profile.saas.yaml",
+    "config/",
     "guardian-contract-v1.md",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "MAINTAINERS.md",
+    "VERSIONING.md"
   ],
   "scripts": {
     "test": "node test/mvp.test.js",
+    "test:journey:unit": "node test/journey-scanner.unit.test.js",
+    "test:journey:integration": "node test/journey-scanner.integration.test.js",
+    "test:journey:all": "node test/journey-scanner.unit.test.js && node test/journey-scanner.integration.test.js",
     "test:phase0": "node test/phase0-reality-lock.test.js",
     "test:phase1": "node test/phase1-baseline-expansion.test.js",
     "test:phase2": "node test/phase2-auto-attempts.test.js",
@@ -59,11 +62,23 @@
     "test:phase5:evidence": "node test/phase5-evidence-run.test.js",
     "test:phase5:all": "node test/phase5-visual.test.js && node test/phase5-evidence-run.test.js",
     "test:phase6": "node test/phase6.test.js && node test/phase6-product.test.js",
-    "test:all": "node test/phase0-reality-lock.test.js && node test/mvp.test.js && node test/phase2.test.js && node test/attempt.test.js && node test/reality.test.js && node test/baseline.test.js && node test/baseline-junit.test.js && node test/snapshot.test.js && node test/soft-failures.test.js && node test/market-criticality.test.js && node test/discovery.test.js && node test/phase5.test.js && node test/phase5-visual.test.js && node test/phase5-evidence-run.test.js && node test/phase6.test.js",
-    "start": "node bin/guardian.js"
+    "test:trust-seal": "node test/trust-seal.test.js",
+    "test:narrative-run": "node test/narrative-run.test.js",
+    "test:hardening": "node test/trust-seal.test.js && node test/narrative-run.test.js",
+    "test:wave1-3": "npx mocha test/success-evaluator.unit.test.js test/wave1-3-success-e2e.test.js --timeout 30000",
+    "test:all": "node test/phase0-reality-lock.test.js && node test/mvp.test.js && node test/phase2.test.js && node test/attempt.test.js && node test/reality.test.js && node test/baseline.test.js && node test/baseline-junit.test.js && node test/snapshot.test.js && node test/soft-failures.test.js && node test/market-criticality.test.js && node test/discovery.test.js && node test/phase5.test.js && node test/phase5-visual.test.js && node test/phase5-evidence-run.test.js && node test/phase6.test.js && node test/trust-seal.test.js && node test/narrative-run.test.js",
+    "release:dry": "npm run test:guardian && node bin/guardian.js --help && node bin/guardian.js --version",
+    "test:guardian": "npx jest test/guardian/stability-scorer.unit.test.js test/guardian/stability.integration.test.js test/guardian/alert-ledger.unit.test.js test/guardian/severity-classification.unit.test.js --testTimeout=50000",
+    "start": "node bin/guardian.js",
+    "sample:generate": "node scripts/generate-sample.js",
+    "template:verify": "node scripts/verify-templates.js"
   },
   "dependencies": {
     "express": "^5.2.1",
     "playwright": "^1.48.2"
+  },
+  "devDependencies": {
+    "archiver": "^6.0.1",
+    "mocha": "^11.7.5"
   }
 }

package/policies/landing-demo.json

@@ -0,0 +1,22 @@
+{
+  "name": "Landing/Demo Policy",
+  "description": "Focused policy for landing pages, demo sites, and pre-launch products. Disables account and revenue flows, emphasizes navigation and CTA integrity.",
+  "failOnSeverity": "CRITICAL",
+  "maxWarnings": 5,
+  "maxInfo": 999,
+  "maxTotalRisk": 999,
+  "failOnNewRegression": false,
+  "failOnSoftFailures": false,
+  "softFailureThreshold": 999,
+  "requireBaseline": false,
+  "disabledAttempts": ["signup", "login", "checkout", "newsletter_signup"],
+  "focusAreas": {
+    "broken_pages": "CRITICAL",
+    "dead_links": "CRITICAL",
+    "seo_fundamentals": "WARNING",
+    "trust_signals": "WARNING",
+    "cta_integrity": "CRITICAL",
+    "performance": "WARNING"
+  },
+  "notes": "Landing/Demo sites should emphasize navigation integrity and CTA validity. Revenue-related issues are deprioritized. Account signup/login and checkout are marked NOT_APPLICABLE."
+}

package/src/enterprise/audit-logger.js

@@ -0,0 +1,166 @@
+/**
+ * Phase 11: Audit Logging System
+ * Immutable, append-only logs for compliance and accountability
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const AUDIT_DIR = path.join(os.homedir(), '.odavl-guardian', 'audit');
+
+// Ensure audit directory exists
+function ensureAuditDir() {
+  if (!fs.existsSync(AUDIT_DIR)) {
+    fs.mkdirSync(AUDIT_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get current audit log file path (monthly rotation)
+ */
+function getAuditLogPath() {
+  ensureAuditDir();
+  
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const filename = `audit-${year}-${month}.jsonl`;
+  
+  return path.join(AUDIT_DIR, filename);
+}
+
+/**
+ * Write an audit log entry
+ */
+function logAudit(action, details = {}) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    user: os.userInfo().username || 'unknown',
+    action,
+    details,
+    hostname: os.hostname(),
+  };
+  
+  const logPath = getAuditLogPath();
+  const logLine = JSON.stringify(entry) + '\n';
+  
+  // Append-only write (immutable)
+  fs.appendFileSync(logPath, logLine, 'utf-8');
+  
+  return entry;
+}
+
+/**
+ * Read audit logs (optionally filtered)
+ */
+function readAuditLogs(options = {}) {
+  ensureAuditDir();
+  
+  const {
+    action = null,
+    user = null,
+    startDate = null,
+    endDate = null,
+    limit = 1000,
+  } = options;
+  
+  const logs = [];
+  const files = fs.readdirSync(AUDIT_DIR)
+    .filter(f => f.startsWith('audit-') && f.endsWith('.jsonl'))
+    .sort()
+    .reverse(); // Most recent first
+  
+  for (const file of files) {
+    const filePath = path.join(AUDIT_DIR, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim());
+    
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        
+        // Apply filters
+        if (action && entry.action !== action) continue;
+        if (user && entry.user !== user) continue;
+        if (startDate && new Date(entry.timestamp) < new Date(startDate)) continue;
+        if (endDate && new Date(entry.timestamp) > new Date(endDate)) continue;
+        
+        logs.push(entry);
+        
+        if (logs.length >= limit) {
+          return logs;
+        }
+      } catch (error) {
+        // Skip invalid lines
+        continue;
+      }
+    }
+  }
+  
+  return logs;
+}
+
+/**
+ * Get audit summary
+ */
+function getAuditSummary() {
+  const logs = readAuditLogs({ limit: 10000 });
+  
+  const actionCounts = {};
+  const userCounts = {};
+  
+  for (const log of logs) {
+    actionCounts[log.action] = (actionCounts[log.action] || 0) + 1;
+    userCounts[log.user] = (userCounts[log.user] || 0) + 1;
+  }
+  
+  return {
+    totalLogs: logs.length,
+    actionCounts,
+    userCounts,
+    firstLog: logs[logs.length - 1]?.timestamp || null,
+    lastLog: logs[0]?.timestamp || null,
+  };
+}
+
+/**
+ * Common audit actions (constants)
+ */
+const AUDIT_ACTIONS = {
+  SCAN_RUN: 'scan:run',
+  SCAN_VIEW: 'scan:view',
+  LIVE_START: 'live:start',
+  LIVE_STOP: 'live:stop',
+  SITE_ADD: 'site:add',
+  SITE_REMOVE: 'site:remove',
+  PLAN_UPGRADE: 'plan:upgrade',
+  USER_ADD: 'user:add',
+  USER_REMOVE: 'user:remove',
+  EXPORT_PDF: 'export:pdf',
+  RECIPE_IMPORT: 'recipe:import',
+  RECIPE_EXPORT: 'recipe:export',
+  RECIPE_REMOVE: 'recipe:remove',
+};
+
+/**
+ * Reset audit logs (for testing only)
+ */
+function resetAuditLogs() {
+  if (fs.existsSync(AUDIT_DIR)) {
+    const files = fs.readdirSync(AUDIT_DIR);
+    for (const file of files) {
+      if (file.startsWith('audit-') && file.endsWith('.jsonl')) {
+        fs.unlinkSync(path.join(AUDIT_DIR, file));
+      }
+    }
+  }
+}
+
+module.exports = {
+  logAudit,
+  readAuditLogs,
+  getAuditSummary,
+  AUDIT_ACTIONS,
+  resetAuditLogs,
+};

package/src/enterprise/pdf-exporter.js

@@ -0,0 +1,267 @@
+/**
+ * Phase 11: PDF Export for Reports
+ * Generate executive-ready PDF reports from Guardian scans
+ * Phase C: Real PDF rendering using Playwright
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { GuardianBrowser } = require('../guardian/browser');
+
+/**
+ * Convert HTML report to real PDF using Playwright
+ * Produces binary PDF with valid %PDF header
+ */
+async function generatePDFReal(reportPath, outputPath) {
+  // Read the HTML report
+  if (!fs.existsSync(reportPath)) {
+    throw new Error(`Report not found: ${reportPath}`);
+  }
+  
+  const html = fs.readFileSync(reportPath, 'utf-8');
+  const metadata = extractReportMetadata(html);
+  
+  // Use Playwright to render to PDF
+  const browser = new GuardianBrowser();
+  
+  try {
+    await browser.launch(30000, { headless: true });
+    
+    // Set content as HTML
+    await browser.page.setContent(html, { waitUntil: 'networkidle' });
+    
+    // Render to PDF (binary format with %PDF header)
+    const pdfBuffer = await browser.page.pdf({
+      format: 'A4',
+      margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' },
+    });
+    
+    // Write binary PDF
+    fs.writeFileSync(outputPath, pdfBuffer);
+    
+    await browser.close();
+    
+    return {
+      outputPath,
+      size: fs.statSync(outputPath).size,
+      metadata,
+      format: 'application/pdf',
+      isRealPDF: true,
+    };
+  } catch (error) {
+    await browser.close().catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * Convert HTML report to PDF
+ * Wrapper that uses real PDF rendering
+ */
+function generatePDF(reportPath, outputPath) {
+  // For synchronous API compatibility, we use generatePDFReal async version
+  // This function should be called via async wrapper
+  throw new Error('Use generatePDFAsync for real PDF rendering');
+}
+
+/**
+ * Async version - generates real PDF
+ */
+async function generatePDFAsync(reportPath, outputPath) {
+  return generatePDFReal(reportPath, outputPath);
+}
+
+/**
+ * Extract metadata from HTML report
+ */
+function extractReportMetadata(html) {
+  const metadata = {
+    url: extractBetween(html, '<h2>URL:', '</h2>') || 'Unknown',
+    timestamp: extractBetween(html, '<p>Scanned:', '</p>') || 'Unknown',
+    verdict: extractVerdict(html),
+    riskLevel: extractRiskLevel(html),
+    flags: extractFlags(html),
+    summary: extractBetween(html, '<h3>Executive Summary</h3>', '<h3>') || '',
+  };
+  
+  return metadata;
+}
+
+/**
+ * Extract text between two markers
+ */
+function extractBetween(text, start, end) {
+  const startIndex = text.indexOf(start);
+  if (startIndex === -1) return null;
+  
+  const searchStart = startIndex + start.length;
+  const endIndex = text.indexOf(end, searchStart);
+  if (endIndex === -1) return null;
+  
+  return text.substring(searchStart, endIndex).trim().replace(/<[^>]*>/g, '');
+}
+
+/**
+ * Extract verdict from HTML
+ */
+function extractVerdict(html) {
+  if (html.includes('PASSED')) return 'PASSED';
+  if (html.includes('FAILED')) return 'FAILED';
+  if (html.includes('WARN')) return 'WARN';
+  return 'UNKNOWN';
+}
+
+/**
+ * Extract risk level
+ */
+function extractRiskLevel(html) {
+  if (html.includes('HIGH RISK')) return 'HIGH';
+  if (html.includes('MEDIUM RISK')) return 'MEDIUM';
+  if (html.includes('LOW RISK')) return 'LOW';
+  return 'UNKNOWN';
+}
+
+/**
+ * Extract flags from report
+ */
+function extractFlags(html) {
+  const flags = [];
+  
+  const flagSection = extractBetween(html, '<h3>Flags Detected</h3>', '<h3>');
+  if (!flagSection) return flags;
+  
+  const lines = flagSection.split('\n');
+  for (const line of lines) {
+    const match = line.match(/([A-Z_]+):/);
+    if (match) {
+      flags.push(match[1]);
+    }
+  }
+  
+  return flags;
+}
+
+/**
+ * Generate simplified PDF (text format)
+ * In production, use a proper PDF library
+ */
+function generateSimplifiedPDF(metadata) {
+  const lines = [
+    '='.repeat(80),
+    'GUARDIAN SECURITY REPORT',
+    '='.repeat(80),
+    '',
+    `URL: ${metadata.url}`,
+    `Scanned: ${metadata.timestamp}`,
+    `Verdict: ${metadata.verdict}`,
+    `Risk Level: ${metadata.riskLevel}`,
+    '',
+    '-'.repeat(80),
+    'EXECUTIVE SUMMARY',
+    '-'.repeat(80),
+    '',
+    metadata.summary || 'No summary available',
+    '',
+    '-'.repeat(80),
+    'FLAGS DETECTED',
+    '-'.repeat(80),
+    '',
+  ];
+  
+  if (metadata.flags.length === 0) {
+    lines.push('No flags detected');
+  } else {
+    for (const flag of metadata.flags) {
+      lines.push(`- ${flag}`);
+    }
+  }
+  
+  lines.push('');
+  lines.push('='.repeat(80));
+  lines.push('Generated by Guardian - Enterprise Edition');
+  lines.push('='.repeat(80));
+  
+  return lines.join('\n');
+}
+
+/**
+ * Export report to PDF (async)
+ * Main entry point - uses real PDF rendering
+ */
+async function exportReportToPDFAsync(reportId, outputDir = null) {
+  // Find report file
+  const artifactsDir = path.join(process.cwd(), 'artifacts');
+  
+  let reportPath = null;
+  
+  // Try direct path first
+  if (fs.existsSync(reportId)) {
+    reportPath = reportId;
+  } else {
+    // Search in artifacts
+    const reportFile = path.join(artifactsDir, reportId, 'index.html');
+    if (fs.existsSync(reportFile)) {
+      reportPath = reportFile;
+    }
+  }
+  
+  if (!reportPath) {
+    throw new Error(`Report not found: ${reportId}`);
+  }
+  
+  // Generate output path
+  const basename = path.basename(reportPath, '.html');
+  const outputFilename = `${basename}-report.pdf`;
+  const outputPath = outputDir
+    ? path.join(outputDir, outputFilename)
+    : path.join(path.dirname(reportPath), outputFilename);
+  
+  return generatePDFAsync(reportPath, outputPath);
+}
+
+/**
+ * Legacy synchronous version (for backward compatibility)
+ */
+function exportReportToPDF(reportId, outputDir = null) {
+  throw new Error('Use exportReportToPDFAsync for PDF export');
+}
+
+/**
+ * List available reports for export
+ */
+function listAvailableReports() {
+  const artifactsDir = path.join(process.cwd(), 'artifacts');
+  
+  if (!fs.existsSync(artifactsDir)) {
+    return [];
+  }
+  
+  const reports = [];
+  const entries = fs.readdirSync(artifactsDir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const reportFile = path.join(artifactsDir, entry.name, 'index.html');
+      if (fs.existsSync(reportFile)) {
+        const stats = fs.statSync(reportFile);
+        reports.push({
+          id: entry.name,
+          path: reportFile,
+          modifiedAt: stats.mtime.toISOString(),
+        });
+      }
+    }
+  }
+  
+  return reports.sort((a, b) => 
+    new Date(b.modifiedAt) - new Date(a.modifiedAt)
+  );
+}
+
+module.exports = {
+  exportReportToPDF,
+  exportReportToPDFAsync,
+  listAvailableReports,
+  generatePDF: generatePDFAsync,
+  generatePDFAsync,
+};