vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/agent-firewall/enforcement/gateway.js

@@ -0,0 +1,1059 @@
+/**
+ * Agent Firewall Enforcement Gateway v3.0
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * AGENT FIREWALL™ - ENFORCEMENT GATEWAY
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * THE SINGLE ENTRY POINT for all enforcement operations.
+ * All intercepted changes MUST flow through this gateway.
+ * 
+ * Features:
+ * - Real-time blocking (blocks at write-time, not after)
+ * - Explainable blocks (exact reason + evidence + fix path)
+ * - Modes: ENFORCE (default), OBSERVE, CI, IDE
+ * - Signed verdicts for audit trail
+ * - Hash chain for tamper detection
+ * 
+ * @module enforcement/gateway
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const path = require("path");
+const fs = require("fs");
+
+// Import schema validator
+const Ajv = require("ajv").default || require("ajv");
+const addFormats = require("ajv-formats").default || require("ajv-formats");
+
+// Import existing modules
+const { IntentStore } = require("../intent/store");
+const { checkAlignment, checkAlignmentBatch, VIOLATION_CODES } = require("../intent/alignment-engine");
+const { verifyIntentIntegrity, isIntentExpired } = require("../intent/schema");
+const { resolveEvidence } = require("../evidence/resolver");
+const { evaluatePolicy } = require("../policy/engine");
+const { SessionCollector } = require("../session/collector");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const MODE = {
+  ENFORCE: "ENFORCE",   // Block on violation (default when intent exists)
+  OBSERVE: "OBSERVE",   // Log only (default when no intent)
+  CI: "CI",             // Fail pipeline on BLOCK
+  IDE: "IDE",           // Real-time interception, block writes
+};
+
+const VERDICT = {
+  PASS: "PASS",
+  BLOCK: "BLOCK",
+  WOULD_PASS: "WOULD_PASS",   // OBSERVE mode
+  WOULD_BLOCK: "WOULD_BLOCK", // OBSERVE mode
+};
+
+// Block patterns - code quality issues that always block
+const BLOCK_PATTERNS = [
+  { pattern: /\bTODO\b/i, code: "TODO_DETECTED", message: "TODO comment found - resolve before shipping" },
+  { pattern: /\bFIXME\b/i, code: "FIXME_DETECTED", message: "FIXME comment found - resolve before shipping" },
+  { pattern: /\bXXX\b/, code: "XXX_DETECTED", message: "XXX placeholder found - resolve before shipping" },
+  { pattern: /mock[A-Z]\w*\s*[=:]/, code: "MOCK_DATA", message: "Mock data detected in code" },
+  { pattern: /fakeDat[ae]|fakeUser|fakeResponse/i, code: "FAKE_DATA", message: "Fake data detected in code" },
+  { pattern: /placeholder|dummy/i, code: "PLACEHOLDER_DETECTED", message: "Placeholder code detected" },
+  { pattern: /console\.(log|debug|info)\(/, code: "CONSOLE_LOG", message: "Console statement in production code", severity: "warn" },
+  { pattern: /:\s*any\b/, code: "ANY_TYPE", message: "TypeScript 'any' type detected", severity: "warn" },
+  { pattern: /throw new Error\(['"]not implemented/i, code: "NOT_IMPLEMENTED", message: "Not implemented error found" },
+  { pattern: /\/\/ @ts-ignore|\/\/ @ts-nocheck/, code: "TS_IGNORE", message: "TypeScript ignore directive", severity: "warn" },
+];
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SCHEMA VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+let ajv = null;
+let validators = {};
+
+function initializeValidators() {
+  if (ajv) return;
+  
+  ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+  
+  try {
+    const schemaDir = path.join(__dirname, "schemas");
+    
+    const intentSchema = JSON.parse(fs.readFileSync(path.join(schemaDir, "intent.schema.json"), "utf-8"));
+    const changeSchema = JSON.parse(fs.readFileSync(path.join(schemaDir, "change-event.schema.json"), "utf-8"));
+    const verdictSchema = JSON.parse(fs.readFileSync(path.join(schemaDir, "verdict.schema.json"), "utf-8"));
+    
+    validators.intent = ajv.compile(intentSchema);
+    validators.changeEvent = ajv.compile(changeSchema);
+    validators.verdict = ajv.compile(verdictSchema);
+  } catch (err) {
+    // Fallback to no validation if schemas not found
+    validators.intent = () => true;
+    validators.changeEvent = () => true;
+    validators.verdict = () => true;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CHANGE EVENT BUILDER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+let changeCounter = 0;
+
+function generateChangeId() {
+  return `chg-${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+function generateVerdictId() {
+  return `vrd-${Date.now().toString(36)}-${crypto.randomBytes(6).toString("hex")}`;
+}
+
+/**
+ * Build a normalized change event from raw input
+ */
+function buildChangeEvent(rawChange, source) {
+  const id = generateChangeId();
+  
+  const event = {
+    id,
+    type: rawChange.type || inferChangeType(rawChange),
+    source: {
+      agent_id: source?.agentId || rawChange.agentId || "unknown",
+      interception_point: source?.interceptionPoint || "cli",
+      tool_name: source?.toolName || null,
+      session_id: source?.sessionId || null,
+    },
+    location: rawChange.path || rawChange.file || rawChange.location,
+    diff: rawChange.diff || null,
+    content: rawChange.content || null,
+    domain: rawChange.domain || classifyDomain(rawChange.path || rawChange.location),
+    claims: rawChange.claims || [],
+    code_quality: null, // Will be populated by analyzeCodeQuality
+    timestamp: new Date().toISOString(),
+    metadata: rawChange.metadata || {},
+  };
+  
+  // Analyze code quality if content is available
+  if (event.content || event.diff?.after) {
+    event.code_quality = analyzeCodeQuality(event.content || event.diff.after);
+  }
+  
+  return event;
+}
+
+/**
+ * Infer change type from raw change
+ */
+function inferChangeType(rawChange) {
+  if (rawChange.type) return rawChange.type;
+  
+  const loc = rawChange.path || rawChange.location || "";
+  
+  // Check for route changes
+  if (rawChange.route || loc.includes("route") || rawChange.method) {
+    return rawChange.diff ? "route_modify" : "route_add";
+  }
+  
+  // Check for env changes
+  if (rawChange.envVar || loc.includes(".env")) {
+    return rawChange.diff ? "env_write" : "env_ref";
+  }
+  
+  // Check for file changes
+  if (rawChange.content && !rawChange.diff) {
+    return "file_create";
+  }
+  
+  return "file_write";
+}
+
+/**
+ * Classify file domain
+ */
+function classifyDomain(filePath) {
+  if (!filePath) return "general";
+  const s = filePath.toLowerCase();
+  
+  if (s.includes("auth") || s.includes("login") || s.includes("session")) return "auth";
+  if (s.includes("stripe") || s.includes("payment") || s.includes("billing")) return "payments";
+  if (s.includes("route") || s.includes("api/") || s.includes("endpoint")) return "routes";
+  if (s.includes("schema") || s.includes("contract") || s.includes("types")) return "contracts";
+  if (s.includes("component") || s.includes("page") || s.includes("/ui/")) return "ui";
+  if (s.includes("database") || s.includes("prisma") || s.includes("migration")) return "database";
+  if (s.includes("config") || s.includes(".env") || s.includes("setting")) return "config";
+  if (s.includes("test") || s.includes("spec") || s.includes("__tests__")) return "tests";
+  
+  return "general";
+}
+
+/**
+ * Analyze code quality in content
+ */
+function analyzeCodeQuality(content) {
+  if (!content) return null;
+  
+  const result = {
+    has_mock_data: false,
+    has_todo: false,
+    has_fixme: false,
+    has_placeholder: false,
+    has_fake_handler: false,
+    has_console_log: false,
+    has_any_type: false,
+    detected_patterns: [],
+  };
+  
+  const lines = content.split("\n");
+  
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    
+    for (const pattern of BLOCK_PATTERNS) {
+      if (pattern.pattern.test(line)) {
+        result.detected_patterns.push({
+          pattern: pattern.code,
+          line: i + 1,
+          severity: pattern.severity || "block",
+          snippet: line.trim().substring(0, 100),
+        });
+        
+        // Set flags
+        if (pattern.code === "TODO_DETECTED") result.has_todo = true;
+        if (pattern.code === "FIXME_DETECTED") result.has_fixme = true;
+        if (pattern.code.includes("MOCK") || pattern.code.includes("FAKE")) result.has_mock_data = true;
+        if (pattern.code === "PLACEHOLDER_DETECTED") result.has_placeholder = true;
+        if (pattern.code === "CONSOLE_LOG") result.has_console_log = true;
+        if (pattern.code === "ANY_TYPE") result.has_any_type = true;
+      }
+    }
+    
+    // Check for fake handlers
+    if (/function\s+\w*[Hh]andler\s*\([^)]*\)\s*\{\s*\}/.test(line) ||
+        /=>\s*\{\s*\}/.test(line) ||
+        /return\s+null\s*;?\s*\/\/\s*todo/i.test(line)) {
+      result.has_fake_handler = true;
+      result.detected_patterns.push({
+        pattern: "FAKE_HANDLER",
+        line: i + 1,
+        severity: "block",
+        snippet: line.trim().substring(0, 100),
+      });
+    }
+  }
+  
+  return result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENFORCEMENT GATEWAY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+class EnforcementGateway {
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.options = options;
+    
+    // Initialize components
+    this.intentStore = new IntentStore(projectRoot);
+    this.sessionCollector = new SessionCollector(projectRoot);
+    
+    // Session tracking
+    this.sessionId = options.sessionId || `session-${Date.now()}`;
+    this.verdictSequence = 0;
+    this.previousVerdictHash = null;
+    
+    // Initialize validators
+    initializeValidators();
+  }
+  
+  /**
+   * Get current mode based on intent and options
+   */
+  getMode() {
+    // Explicit mode override
+    if (this.options.mode) return this.options.mode;
+    
+    // Environment override
+    if (process.env.VIBECHECK_FIREWALL_MODE) {
+      return process.env.VIBECHECK_FIREWALL_MODE.toUpperCase();
+    }
+    
+    // CI detection
+    if (process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI) {
+      return MODE.CI;
+    }
+    
+    // Default: OBSERVE if no intent, ENFORCE if intent exists
+    return this.intentStore.hasIntent() ? MODE.ENFORCE : MODE.OBSERVE;
+  }
+  
+  /**
+   * MAIN ENTRY POINT - Intercept and evaluate a change
+   * 
+   * This is THE function all interception points should call.
+   * Returns a verdict that determines if the change is allowed.
+   * 
+   * @param {Object} rawChange - Raw change data
+   * @param {Object} source - Source information (agent, interception point)
+   * @returns {Promise<Object>} Verdict with decision and details
+   */
+  async intercept(rawChange, source = {}) {
+    const startTime = Date.now();
+    const mode = this.getMode();
+    
+    // Build normalized change event
+    const changeEvent = buildChangeEvent(rawChange, source);
+    
+    // Get current intent
+    const intent = this.intentStore.getCurrent({ allowMissing: true });
+    const hasIntent = this.intentStore.hasIntent();
+    
+    // In OBSERVE mode without intent, log and allow
+    if (mode === MODE.OBSERVE && !hasIntent) {
+      this.sessionCollector.record({
+        type: changeEvent.type,
+        path: changeEvent.location,
+        agent_id: changeEvent.source.agent_id,
+        lines_added: changeEvent.diff?.lines_added || 0,
+        lines_removed: changeEvent.diff?.lines_removed || 0,
+      });
+      
+      return this._buildVerdict({
+        decision: VERDICT.WOULD_PASS,
+        mode,
+        intent_hash: null,
+        change_events: [changeEvent.id],
+        violations: [],
+        proofs: [],
+        summary: "OBSERVE mode - change logged for later review",
+        duration_ms: Date.now() - startTime,
+      });
+    }
+    
+    // Run enforcement checks
+    const violations = [];
+    
+    // 1. Intent integrity check
+    if (intent) {
+      const integrityCheck = verifyIntentIntegrity(intent);
+      if (!integrityCheck.valid) {
+        violations.push(this._buildViolation(
+          VIOLATION_CODES.INTENT_CORRUPTED,
+          "intent_integrity",
+          `Intent integrity failed: ${integrityCheck.reason}`,
+          "intent",
+          { expected: "valid hash", actual: "hash mismatch" }
+        ));
+      }
+      
+      if (isIntentExpired(intent)) {
+        violations.push(this._buildViolation(
+          VIOLATION_CODES.INTENT_EXPIRED,
+          "intent_expiration",
+          "Intent has expired - declare new intent",
+          "intent",
+          { expected: "not expired", actual: `expired at ${intent.expires_at}` }
+        ));
+      }
+    }
+    
+    // 2. Intent alignment check
+    const alignmentResult = checkAlignment(intent, changeEvent);
+    if (!alignmentResult.aligned) {
+      violations.push(...alignmentResult.violations);
+    }
+    
+    // 3. Code quality check
+    if (changeEvent.code_quality) {
+      const qualityViolations = this._checkCodeQuality(changeEvent);
+      violations.push(...qualityViolations);
+    }
+    
+    // 4. Domain/scope check
+    if (intent?.scope) {
+      const scopeViolations = this._checkScope(changeEvent, intent);
+      violations.push(...scopeViolations);
+    }
+    
+    // 5. Protected files check
+    if (intent?.scope?.protected_files) {
+      const protectedViolations = this._checkProtectedFiles(changeEvent, intent);
+      violations.push(...protectedViolations);
+    }
+    
+    // 6. Evidence resolution (existing system)
+    const evidence = resolveEvidence(this.projectRoot, changeEvent.claims || []);
+    
+    // 7. Policy evaluation (existing system)
+    const policyResult = await evaluatePolicy({
+      policy: this._loadPolicy(),
+      claims: changeEvent.claims || [],
+      evidence,
+      files: [{ path: changeEvent.location, domain: changeEvent.domain }],
+      intent: intent?.summary || "",
+    });
+    
+    if (policyResult.violations) {
+      violations.push(...policyResult.violations.map(v => this._buildViolation(
+        v.rule?.toUpperCase().replace(/-/g, "_") || "POLICY_VIOLATION",
+        v.rule || "policy",
+        v.message || "Policy violation",
+        v.claimId || v.file || "unknown"
+      )));
+    }
+    
+    // Build proofs from evidence
+    const proofs = evidence.map(e => ({
+      id: `prf-${e.type}-${crypto.randomBytes(4).toString("hex")}`,
+      type: this._mapClaimTypeToProofType(e.type),
+      status: e.result === "PROVEN" ? "verified" : e.result === "UNPROVEN" ? "failed" : "pending",
+      target: e.pointer || e.claimId,
+      trace: e.sources?.[0]?.pointer,
+      verified_at: new Date().toISOString(),
+      method: "static",
+      error: e.result !== "PROVEN" ? e.reason : null,
+    }));
+    
+    // Determine final decision
+    const blockViolations = violations.filter(v => v.severity === "block");
+    let decision;
+    
+    if (mode === MODE.OBSERVE) {
+      decision = blockViolations.length > 0 ? VERDICT.WOULD_BLOCK : VERDICT.WOULD_PASS;
+    } else {
+      decision = blockViolations.length > 0 ? VERDICT.BLOCK : VERDICT.PASS;
+    }
+    
+    // Build verdict
+    const verdict = this._buildVerdict({
+      decision,
+      mode,
+      intent_hash: intent?.hash || null,
+      change_events: [changeEvent.id],
+      violations,
+      proofs,
+      summary: this._generateSummary(decision, violations),
+      duration_ms: Date.now() - startTime,
+    });
+    
+    // Store verdict
+    this._storeVerdict(verdict);
+    
+    // In OBSERVE mode, still log to session
+    if (mode === MODE.OBSERVE) {
+      this.sessionCollector.record({
+        type: changeEvent.type,
+        path: changeEvent.location,
+        agent_id: changeEvent.source.agent_id,
+        verdict_id: verdict.id,
+        would_block: verdict.decision === VERDICT.WOULD_BLOCK,
+      });
+    }
+    
+    return verdict;
+  }
+  
+  /**
+   * Intercept multiple changes in batch
+   */
+  async interceptBatch(rawChanges, source = {}) {
+    const startTime = Date.now();
+    const mode = this.getMode();
+    
+    // Build normalized change events
+    const changeEvents = rawChanges.map(rc => buildChangeEvent(rc, source));
+    
+    // Get intent
+    const intent = this.intentStore.getCurrent({ allowMissing: true });
+    const hasIntent = this.intentStore.hasIntent();
+    
+    // In OBSERVE mode without intent
+    if (mode === MODE.OBSERVE && !hasIntent) {
+      for (const ce of changeEvents) {
+        this.sessionCollector.record({
+          type: ce.type,
+          path: ce.location,
+          agent_id: ce.source.agent_id,
+        });
+      }
+      
+      return this._buildVerdict({
+        decision: VERDICT.WOULD_PASS,
+        mode,
+        intent_hash: null,
+        change_events: changeEvents.map(e => e.id),
+        violations: [],
+        proofs: [],
+        summary: "OBSERVE mode - changes logged for later review",
+        duration_ms: Date.now() - startTime,
+      });
+    }
+    
+    // Run batch alignment
+    const alignmentResult = checkAlignmentBatch(intent, changeEvents);
+    const violations = [...alignmentResult.violations];
+    
+    // Check code quality for each
+    for (const ce of changeEvents) {
+      if (ce.code_quality) {
+        violations.push(...this._checkCodeQuality(ce));
+      }
+    }
+    
+    // Determine decision
+    const blockViolations = violations.filter(v => v.severity === "block");
+    let decision;
+    
+    if (mode === MODE.OBSERVE) {
+      decision = blockViolations.length > 0 ? VERDICT.WOULD_BLOCK : VERDICT.WOULD_PASS;
+    } else {
+      decision = blockViolations.length > 0 ? VERDICT.BLOCK : VERDICT.PASS;
+    }
+    
+    const verdict = this._buildVerdict({
+      decision,
+      mode,
+      intent_hash: intent?.hash || null,
+      change_events: changeEvents.map(e => e.id),
+      violations,
+      proofs: [],
+      summary: this._generateSummary(decision, violations),
+      duration_ms: Date.now() - startTime,
+    });
+    
+    this._storeVerdict(verdict);
+    
+    return verdict;
+  }
+  
+  /**
+   * Quick check - fast path for simple validation
+   */
+  quickCheck(rawChange) {
+    const changeEvent = buildChangeEvent(rawChange, {});
+    const intent = this.intentStore.getCurrent({ allowMissing: true });
+    const alignmentResult = checkAlignment(intent, changeEvent);
+    
+    return {
+      allowed: alignmentResult.aligned,
+      decision: alignmentResult.decision,
+      violations: alignmentResult.violations,
+      intent_hash: intent?.hash || null,
+    };
+  }
+  
+  /**
+   * Get verdict required for ship
+   */
+  async getShipVerdict(options = {}) {
+    const latestVerdict = this._getLatestVerdict();
+    
+    if (!latestVerdict) {
+      return {
+        can_ship: false,
+        reason: "NO_VERDICT",
+        message: "No enforcement verdict found. Run vibecheck shield first.",
+      };
+    }
+    
+    // Verify verdict integrity
+    const integrity = this._verifyVerdictIntegrity(latestVerdict);
+    if (!integrity.valid) {
+      return {
+        can_ship: false,
+        reason: "VERDICT_TAMPERED",
+        message: `Verdict integrity check failed: ${integrity.reason}`,
+      };
+    }
+    
+    // Check verdict is recent enough
+    const verdictAge = Date.now() - new Date(latestVerdict.timestamp).getTime();
+    const maxAge = options.maxAge || 30 * 60 * 1000; // 30 minutes default
+    
+    if (verdictAge > maxAge) {
+      return {
+        can_ship: false,
+        reason: "VERDICT_STALE",
+        message: `Verdict is ${Math.round(verdictAge / 60000)} minutes old. Re-run vibecheck shield.`,
+      };
+    }
+    
+    return {
+      can_ship: latestVerdict.decision === VERDICT.PASS,
+      verdict: latestVerdict,
+      reason: latestVerdict.decision,
+      message: latestVerdict.summary,
+    };
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PRIVATE METHODS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  _buildViolation(code, rule, message, resource, evidence = null) {
+    const violation = {
+      code,
+      rule,
+      message,
+      resource,
+      intent_ref: rule,
+      severity: "block",
+      evidence: evidence || null,
+      fix_hint: this._getFixHint(code, resource),
+    };
+    
+    return violation;
+  }
+  
+  _buildVerdict({ decision, mode, intent_hash, change_events, violations, proofs, summary, duration_ms }) {
+    const id = generateVerdictId();
+    const timestamp = new Date().toISOString();
+    
+    this.verdictSequence++;
+    
+    const verdict = {
+      id,
+      decision,
+      mode,
+      violations,
+      proofs,
+      intent_hash,
+      change_events,
+      timestamp,
+      verdict_hash: "", // Will be computed
+      signature: null,
+      chain: {
+        previous_verdict_hash: this.previousVerdictHash,
+        sequence_number: this.verdictSequence,
+        session_id: this.sessionId,
+      },
+      summary,
+      block_message: decision === VERDICT.BLOCK ? this._formatBlockMessage(violations) : null,
+      fix_guidance: this._generateFixGuidance(violations),
+      metadata: {
+        run_id: crypto.randomBytes(8).toString("hex"),
+        agent_id: change_events[0]?.source?.agent_id || "unknown",
+        project_root: this.projectRoot,
+        file_count: change_events.length,
+        evaluation_duration_ms: duration_ms,
+        vibecheck_version: "3.0.0",
+      },
+    };
+    
+    // Compute verdict hash
+    verdict.verdict_hash = this._computeVerdictHash(verdict);
+    
+    // Sign verdict
+    verdict.signature = this._signVerdict(verdict);
+    
+    // Update chain
+    this.previousVerdictHash = verdict.verdict_hash;
+    
+    return verdict;
+  }
+  
+  _checkCodeQuality(changeEvent) {
+    const violations = [];
+    const cq = changeEvent.code_quality;
+    
+    if (!cq || !cq.detected_patterns) return violations;
+    
+    for (const pattern of cq.detected_patterns) {
+      if (pattern.severity === "block") {
+        violations.push(this._buildViolation(
+          pattern.pattern,
+          "code_quality",
+          BLOCK_PATTERNS.find(p => p.code === pattern.pattern)?.message || `Code quality issue: ${pattern.pattern}`,
+          changeEvent.location,
+          {
+            file: changeEvent.location,
+            line: pattern.line,
+            snippet: pattern.snippet,
+          }
+        ));
+      }
+    }
+    
+    return violations;
+  }
+  
+  _checkScope(changeEvent, intent) {
+    const violations = [];
+    
+    if (intent.scope?.directories) {
+      const loc = changeEvent.location;
+      const inScope = intent.scope.directories.some(dir => 
+        loc.startsWith(dir) || loc.includes(`/${dir}`) || loc.includes(`\\${dir}`)
+      );
+      
+      if (!inScope) {
+        violations.push(this._buildViolation(
+          VIOLATION_CODES.SCOPE_VIOLATION,
+          "scope_check",
+          `File outside allowed directories: ${changeEvent.location}`,
+          changeEvent.location,
+          {
+            expected: intent.scope.directories.join(", "),
+            actual: changeEvent.location,
+          }
+        ));
+      }
+    }
+    
+    if (intent.scope?.domains) {
+      if (!intent.scope.domains.includes(changeEvent.domain)) {
+        violations.push(this._buildViolation(
+          VIOLATION_CODES.DOMAIN_VIOLATION,
+          "domain_check",
+          `Domain '${changeEvent.domain}' not in allowed domains`,
+          changeEvent.location,
+          {
+            expected: intent.scope.domains.join(", "),
+            actual: changeEvent.domain,
+          }
+        ));
+      }
+    }
+    
+    if (intent.scope?.excluded_paths) {
+      const isExcluded = intent.scope.excluded_paths.some(ex =>
+        changeEvent.location.includes(ex)
+      );
+      
+      if (isExcluded) {
+        violations.push(this._buildViolation(
+          VIOLATION_CODES.SCOPE_VIOLATION,
+          "excluded_path",
+          `File is in excluded paths: ${changeEvent.location}`,
+          changeEvent.location
+        ));
+      }
+    }
+    
+    return violations;
+  }
+  
+  _checkProtectedFiles(changeEvent, intent) {
+    const violations = [];
+    
+    for (const protectedFile of intent.scope.protected_files) {
+      if (changeEvent.location.includes(protectedFile)) {
+        violations.push(this._buildViolation(
+          "PROTECTED_FILE_MODIFICATION",
+          "protected_file",
+          `Protected file cannot be modified: ${protectedFile}`,
+          changeEvent.location
+        ));
+      }
+    }
+    
+    return violations;
+  }
+  
+  _computeVerdictHash(verdict) {
+    const content = JSON.stringify({
+      decision: verdict.decision,
+      mode: verdict.mode,
+      violations: verdict.violations.map(v => ({ code: v.code, resource: v.resource })),
+      proofs: verdict.proofs.map(p => ({ id: p.id, status: p.status })),
+      intent_hash: verdict.intent_hash,
+      timestamp: verdict.timestamp,
+      chain: verdict.chain,
+    });
+    
+    return crypto.createHash("sha256").update(content).digest("hex");
+  }
+  
+  _signVerdict(verdict) {
+    // Use HMAC signing with a local key (would be replaced with proper key management)
+    const secret = process.env.VIBECHECK_SIGN_KEY || "vibecheck-local-signing-key";
+    const signature = crypto.createHmac("sha256", secret)
+      .update(verdict.verdict_hash)
+      .digest("hex");
+    
+    return {
+      algorithm: "sha256-hmac",
+      value: signature,
+      key_id: "local",
+      signed_at: new Date().toISOString(),
+    };
+  }
+  
+  _verifyVerdictIntegrity(verdict) {
+    if (!verdict || !verdict.verdict_hash) {
+      return { valid: false, reason: "MISSING_HASH" };
+    }
+    
+    const computed = this._computeVerdictHash(verdict);
+    
+    if (computed !== verdict.verdict_hash) {
+      return { valid: false, reason: "HASH_MISMATCH" };
+    }
+    
+    // Verify signature if present
+    if (verdict.signature && verdict.signature.algorithm === "sha256-hmac") {
+      const secret = process.env.VIBECHECK_SIGN_KEY || "vibecheck-local-signing-key";
+      const expected = crypto.createHmac("sha256", secret)
+        .update(verdict.verdict_hash)
+        .digest("hex");
+      
+      if (expected !== verdict.signature.value) {
+        return { valid: false, reason: "SIGNATURE_INVALID" };
+      }
+    }
+    
+    return { valid: true, reason: "VERIFIED" };
+  }
+  
+  _formatBlockMessage(violations) {
+    if (violations.length === 0) {
+      return "BLOCKED_BY_AGENT_FIREWALL: Unknown reason";
+    }
+    
+    const lines = ["═══════════════════════════════════════════════════════════════════════════════"];
+    lines.push("BLOCKED BY AGENT FIREWALL");
+    lines.push("═══════════════════════════════════════════════════════════════════════════════");
+    lines.push("");
+    
+    for (const v of violations.filter(v => v.severity === "block").slice(0, 5)) {
+      lines.push(`❌ [${v.code}]`);
+      lines.push(`   Resource: ${v.resource}`);
+      lines.push(`   Reason: ${v.message}`);
+      
+      if (v.evidence) {
+        if (v.evidence.file) lines.push(`   File: ${v.evidence.file}:${v.evidence.line || ''}`);
+        if (v.evidence.snippet) lines.push(`   Snippet: ${v.evidence.snippet.substring(0, 60)}...`);
+      }
+      
+      if (v.fix_hint) {
+        lines.push(`   Fix: ${v.fix_hint}`);
+      }
+      
+      lines.push("");
+    }
+    
+    if (violations.length > 5) {
+      lines.push(`... and ${violations.length - 5} more violations`);
+      lines.push("");
+    }
+    
+    lines.push("═══════════════════════════════════════════════════════════════════════════════");
+    
+    return lines.join("\n");
+  }
+  
+  _generateSummary(decision, violations) {
+    if (decision === VERDICT.PASS || decision === VERDICT.WOULD_PASS) {
+      return "All enforcement checks passed";
+    }
+    
+    const blockCount = violations.filter(v => v.severity === "block").length;
+    const warnCount = violations.filter(v => v.severity === "warn").length;
+    
+    const topIssues = violations
+      .filter(v => v.severity === "block")
+      .slice(0, 3)
+      .map(v => v.code)
+      .join(", ");
+    
+    return `BLOCKED: ${blockCount} violation(s), ${warnCount} warning(s). Top issues: ${topIssues}`;
+  }
+  
+  _generateFixGuidance(violations) {
+    const guidance = [];
+    
+    for (const v of violations.filter(v => v.severity === "block")) {
+      const fix = this._getFixGuidanceForViolation(v);
+      if (fix) guidance.push(fix);
+    }
+    
+    return guidance;
+  }
+  
+  _getFixGuidanceForViolation(violation) {
+    const fixMap = {
+      "TODO_DETECTED": {
+        action: "remove_code",
+        explanation: "Remove or resolve TODO comment before shipping",
+        auto_fixable: false,
+      },
+      "FIXME_DETECTED": {
+        action: "remove_code",
+        explanation: "Resolve FIXME issue before shipping",
+        auto_fixable: false,
+      },
+      "MOCK_DATA": {
+        action: "modify_file",
+        explanation: "Replace mock data with real implementation or move to test files",
+        auto_fixable: false,
+      },
+      "UNDECLARED_ROUTE": {
+        action: "update_intent",
+        command: "vibecheck intent amend --allow-route",
+        explanation: "Add route to allowed_changes in intent",
+        auto_fixable: false,
+      },
+      "UNDECLARED_ENV_VAR": {
+        action: "add_env",
+        command: "vibecheck intent amend --allow-env",
+        explanation: "Declare env var in intent or add to .env",
+        auto_fixable: true,
+      },
+      "SCOPE_VIOLATION": {
+        action: "update_intent",
+        command: "vibecheck intent amend --allow-dir",
+        explanation: "Expand scope to include this directory",
+        auto_fixable: false,
+      },
+    };
+    
+    const template = fixMap[violation.code];
+    if (!template) return null;
+    
+    return {
+      violation_code: violation.code,
+      target: violation.resource,
+      ...template,
+    };
+  }
+  
+  _getFixHint(code, resource) {
+    const hints = {
+      "TODO_DETECTED": "Remove TODO or resolve the issue",
+      "FIXME_DETECTED": "Fix the issue or remove FIXME comment",
+      "MOCK_DATA": "Replace mock data with real implementation",
+      "FAKE_DATA": "Replace fake data with real implementation",
+      "PLACEHOLDER_DETECTED": "Replace placeholder with real code",
+      "CONSOLE_LOG": "Remove console statement or use proper logger",
+      "ANY_TYPE": "Add proper TypeScript type",
+      "NOT_IMPLEMENTED": "Implement the function",
+      "TS_IGNORE": "Fix the TypeScript error instead of ignoring",
+      "UNDECLARED_ROUTE": `Run: vibecheck intent amend --allow-route "${resource}"`,
+      "UNDECLARED_ENV_VAR": `Run: vibecheck intent amend --allow-env "${resource}"`,
+      "UNDECLARED_FILE_CHANGE": `Run: vibecheck intent amend --allow-file "${resource}"`,
+      "SCOPE_VIOLATION": `Update intent scope or move file to allowed directory`,
+      "DOMAIN_NOT_ALLOWED": `Add domain to intent: vibecheck intent amend --domain`,
+    };
+    
+    return hints[code] || "Review and fix the violation";
+  }
+  
+  _mapClaimTypeToProofType(claimType) {
+    const map = {
+      route: "route",
+      auth_boundary: "auth",
+      ui_success_claim: "ui",
+      http_call: "integration",
+      env_used: "env",
+      env_declared: "env",
+      data_contract: "contract",
+    };
+    return map[claimType] || "integration";
+  }
+  
+  _loadPolicy() {
+    const policyPath = path.join(this.projectRoot, ".vibecheck", "policy.json");
+    
+    if (fs.existsSync(policyPath)) {
+      try {
+        return JSON.parse(fs.readFileSync(policyPath, "utf-8"));
+      } catch {
+        // Return default
+      }
+    }
+    
+    return {
+      version: "3.0.0",
+      profile: "strict",
+      rules: {},
+    };
+  }
+  
+  _storeVerdict(verdict) {
+    const verdictDir = path.join(this.projectRoot, ".vibecheck", "verdicts");
+    
+    try {
+      if (!fs.existsSync(verdictDir)) {
+        fs.mkdirSync(verdictDir, { recursive: true });
+      }
+      
+      // Store by ID
+      fs.writeFileSync(
+        path.join(verdictDir, `${verdict.id}.json`),
+        JSON.stringify(verdict, null, 2)
+      );
+      
+      // Store as latest
+      fs.writeFileSync(
+        path.join(verdictDir, "latest.json"),
+        JSON.stringify(verdict, null, 2)
+      );
+    } catch (err) {
+      // Silent fail - verdict storage is not critical
+    }
+  }
+  
+  _getLatestVerdict() {
+    const latestPath = path.join(this.projectRoot, ".vibecheck", "verdicts", "latest.json");
+    
+    if (fs.existsSync(latestPath)) {
+      try {
+        return JSON.parse(fs.readFileSync(latestPath, "utf-8"));
+      } catch {
+        return null;
+      }
+    }
+    
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FACTORY FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create an enforcement gateway instance
+ */
+function createGateway(projectRoot, options = {}) {
+  return new EnforcementGateway(projectRoot, options);
+}
+
+/**
+ * Quick intercept - one-shot enforcement without persisting gateway
+ */
+async function intercept(projectRoot, rawChange, source = {}) {
+  const gateway = createGateway(projectRoot);
+  return gateway.intercept(rawChange, source);
+}
+
+/**
+ * Quick check - fast validation without full enforcement
+ */
+function quickCheck(projectRoot, rawChange) {
+  const gateway = createGateway(projectRoot);
+  return gateway.quickCheck(rawChange);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  EnforcementGateway,
+  createGateway,
+  intercept,
+  quickCheck,
+  buildChangeEvent,
+  analyzeCodeQuality,
+  classifyDomain,
+  MODE,
+  VERDICT,
+  BLOCK_PATTERNS,
+};