@vibecheckai/cli 3.7.0 → 3.9.0

package/bin/runners/lib/agent-firewall/enforcement/verdict-v2.js

@@ -0,0 +1,333 @@
+/**
+ * Verdict System v2 - Deterministic Enforcement Verdicts
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * AGENT FIREWALL™ - VERDICT SYSTEM
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Every Agent Firewall run MUST end in exactly one verdict:
+ * - PASS (intent + proof satisfied)
+ * - BLOCK (default on any violation)
+ * 
+ * NO "partial success".
+ * NO "best effort".
+ * NO "WARN" as a final state in ENFORCE mode.
+ * 
+ * Verdicts are:
+ * - Deterministic
+ * - Signed/hashed
+ * - Stored for reuse
+ * 
+ * @module enforcement/verdict-v2
+ * @version 2.0.0
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+
+/**
+ * Verdict decisions - only two options
+ */
+const VERDICT = {
+  PASS: "PASS",
+  BLOCK: "BLOCK",
+};
+
+/**
+ * Observation decision (for OBSERVE mode only)
+ */
+const OBSERVATION = {
+  WOULD_PASS: "WOULD_PASS",
+  WOULD_BLOCK: "WOULD_BLOCK",
+};
+
+/**
+ * Firewall modes
+ */
+const MODE = {
+  ENFORCE: "ENFORCE",  // Default: block on violation
+  OBSERVE: "OBSERVE",  // Log + warn only (returns WOULD_* verdicts)
+  CI: "CI",            // Fail pipeline on BLOCK
+  IDE: "IDE",          // Real-time interception, block writes
+};
+
+/**
+ * Verdict object structure
+ * @typedef {Object} Verdict
+ * @property {string} decision - PASS or BLOCK
+ * @property {string} mode - Mode used for evaluation
+ * @property {Object[]} violations - All violations found
+ * @property {Object[]} proofs - All proofs collected
+ * @property {string} intent_hash - Hash of intent used
+ * @property {string} verdict_hash - Hash of entire verdict for signing
+ * @property {string} timestamp - ISO timestamp
+ * @property {string} id - Unique verdict ID
+ */
+
+/**
+ * Generate verdict ID
+ * @returns {string} Unique verdict ID
+ */
+function generateVerdictId() {
+  return `vrd-${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+/**
+ * Compute verdict hash for integrity/signing
+ * @param {Object} verdict - Verdict object (without hash)
+ * @returns {string} SHA-256 hash
+ */
+function 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,
+  });
+  
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Generate deterministic verdict from alignment and proof results
+ * 
+ * RULES:
+ * - If ANY violation exists → BLOCK
+ * - If ANY required proof failed → BLOCK
+ * - If intent is missing → BLOCK
+ * - Only if ALL checks pass → PASS
+ * 
+ * @param {Object} params - Verdict parameters
+ * @param {Object} params.alignmentResult - Result from alignment engine
+ * @param {Object[]} params.proofs - Array of proof artifacts
+ * @param {string} params.mode - Firewall mode
+ * @param {string} params.intent_hash - Hash of intent used
+ * @returns {Verdict} Final verdict
+ */
+function generateVerdict({ alignmentResult, proofs = [], mode = MODE.ENFORCE, intent_hash = null }) {
+  const timestamp = new Date().toISOString();
+  const id = generateVerdictId();
+  
+  // Collect all violations
+  const violations = alignmentResult?.violations || [];
+  
+  // Check for failed proofs
+  const failedProofs = proofs.filter(p => p.status === "failed" || p.status === "unverified");
+  for (const proof of failedProofs) {
+    violations.push({
+      code: "PROOF_FAILED",
+      rule: `proof_${proof.type}`,
+      message: `Required proof failed: ${proof.type} - ${proof.id}`,
+      resource: proof.target || "unknown",
+      intent_ref: "reality_proof",
+      severity: "block",
+    });
+  }
+  
+  // Determine decision
+  // In ENFORCE/CI mode: any violation = BLOCK
+  // In OBSERVE mode: violations generate WOULD_BLOCK but don't actually block
+  let decision;
+  
+  if (mode === MODE.OBSERVE) {
+    decision = violations.length > 0 ? OBSERVATION.WOULD_BLOCK : OBSERVATION.WOULD_PASS;
+  } else {
+    // ENFORCE, CI, IDE - strict enforcement
+    decision = violations.length > 0 ? VERDICT.BLOCK : VERDICT.PASS;
+  }
+  
+  const verdict = {
+    id,
+    decision,
+    mode,
+    violations,
+    proofs: proofs.map(p => ({
+      id: p.id,
+      type: p.type,
+      status: p.status,
+      trace: p.trace,
+    })),
+    intent_hash,
+    timestamp,
+    verdict_hash: "", // Will be computed
+    
+    // Summary for humans
+    summary: generateSummary(decision, violations, proofs),
+    
+    // Machine-readable status
+    passed: decision === VERDICT.PASS || decision === OBSERVATION.WOULD_PASS,
+    blocked: decision === VERDICT.BLOCK || decision === OBSERVATION.WOULD_BLOCK,
+    violation_count: violations.length,
+    proof_count: proofs.length,
+    failed_proof_count: failedProofs.length,
+  };
+  
+  // Compute and set hash
+  verdict.verdict_hash = computeVerdictHash(verdict);
+  
+  return verdict;
+}
+
+/**
+ * Generate human-readable summary
+ * @param {string} decision - Verdict decision
+ * @param {Object[]} violations - Violations array
+ * @param {Object[]} proofs - Proofs array
+ * @returns {string} Summary text
+ */
+function generateSummary(decision, violations, proofs) {
+  if (decision === VERDICT.PASS || decision === OBSERVATION.WOULD_PASS) {
+    return `All checks passed. Intent aligned, ${proofs.length} proofs verified.`;
+  }
+  
+  const violationSummary = violations.slice(0, 3)
+    .map(v => v.message)
+    .join("; ");
+  
+  const extra = violations.length > 3 ? ` (+${violations.length - 3} more)` : "";
+  
+  return `BLOCKED: ${violations.length} violation(s). ${violationSummary}${extra}`;
+}
+
+/**
+ * Generate block message with exact reason and reference
+ * @param {Object[]} violations - Violations array
+ * @returns {string} Formatted block message
+ */
+function formatBlockMessage(violations) {
+  if (violations.length === 0) {
+    return "BLOCKED_BY_AGENT_FIREWALL: Unknown reason";
+  }
+  
+  const lines = ["BLOCKED_BY_AGENT_FIREWALL:"];
+  
+  for (const violation of violations) {
+    lines.push(`- reason: ${violation.code}`);
+    lines.push(`  resource: ${violation.resource}`);
+    lines.push(`  intent_ref: ${violation.intent_ref}`);
+    if (violation.message) {
+      lines.push(`  message: ${violation.message}`);
+    }
+    lines.push("");
+  }
+  
+  return lines.join("\n");
+}
+
+/**
+ * Verify verdict integrity
+ * @param {Object} verdict - Verdict to verify
+ * @returns {Object} Verification result
+ */
+function verifyVerdictIntegrity(verdict) {
+  if (!verdict || !verdict.verdict_hash) {
+    return {
+      valid: false,
+      reason: "MISSING_HASH",
+    };
+  }
+  
+  const computed = computeVerdictHash(verdict);
+  
+  return {
+    valid: computed === verdict.verdict_hash,
+    reason: computed === verdict.verdict_hash ? "VERIFIED" : "HASH_MISMATCH",
+    computed_hash: computed,
+    stored_hash: verdict.verdict_hash,
+  };
+}
+
+/**
+ * Convert legacy verdict (ALLOW/WARN/BLOCK) to v2 format
+ * @param {Object} legacyVerdict - Legacy verdict object
+ * @param {string} mode - Firewall mode
+ * @returns {Verdict} V2 verdict
+ */
+function convertLegacyVerdict(legacyVerdict, mode = MODE.ENFORCE) {
+  const violations = (legacyVerdict.violations || []).map(v => ({
+    code: v.rule?.toUpperCase().replace(/-/g, "_") || "UNKNOWN",
+    rule: v.rule || "unknown",
+    message: v.message || "No message",
+    resource: v.claimId || v.file || "unknown",
+    intent_ref: "legacy",
+    severity: v.severity || "block",
+  }));
+  
+  // In v2, WARN becomes BLOCK in ENFORCE mode
+  let decision;
+  if (mode === MODE.OBSERVE) {
+    decision = legacyVerdict.decision === "ALLOW" 
+      ? OBSERVATION.WOULD_PASS 
+      : OBSERVATION.WOULD_BLOCK;
+  } else {
+    // ALLOW stays PASS, WARN and BLOCK become BLOCK
+    decision = legacyVerdict.decision === "ALLOW" ? VERDICT.PASS : VERDICT.BLOCK;
+  }
+  
+  return generateVerdict({
+    alignmentResult: { violations },
+    proofs: [],
+    mode,
+    intent_hash: null,
+  });
+}
+
+/**
+ * Create verdict manifest for artifact storage
+ * @param {Object} verdict - Verdict object
+ * @param {Object} metadata - Additional metadata
+ * @returns {Object} Manifest object
+ */
+function createVerdictManifest(verdict, metadata = {}) {
+  return {
+    schema_version: "2.0.0",
+    verdict: {
+      id: verdict.id,
+      decision: verdict.decision,
+      hash: verdict.verdict_hash,
+      timestamp: verdict.timestamp,
+    },
+    intent: {
+      hash: verdict.intent_hash,
+    },
+    violations: verdict.violations.map(v => ({
+      code: v.code,
+      resource: v.resource,
+      intent_ref: v.intent_ref,
+    })),
+    proofs: verdict.proofs.map(p => ({
+      id: p.id,
+      type: p.type,
+      status: p.status,
+    })),
+    summary: verdict.summary,
+    metadata: {
+      mode: verdict.mode,
+      ...metadata,
+    },
+    created_at: new Date().toISOString(),
+  };
+}
+
+module.exports = {
+  VERDICT,
+  OBSERVATION,
+  MODE,
+  generateVerdict,
+  generateVerdictId,
+  computeVerdictHash,
+  verifyVerdictIntegrity,
+  formatBlockMessage,
+  generateSummary,
+  convertLegacyVerdict,
+  createVerdictManifest,
+};

package/bin/runners/lib/agent-firewall/index.js

@@ -0,0 +1,200 @@
+/**
+ * Agent Firewall - Unified Entry Point
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * AGENT FIREWALL™ v3.0 - ENFORCEMENT INFRASTRUCTURE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * THE SINGLE ENTRY POINT for all Agent Firewall functionality.
+ * 
+ * This module consolidates:
+ * - Intent system (capture, store, validate)
+ * - Enforcement gateway (intercept, evaluate, verdict)
+ * - Interception layer (MCP, file writes, git hooks)
+ * - Integration layer (ship, packs, seal, CI)
+ * 
+ * All code should import from this module.
+ * 
+ * Example:
+ * ```javascript
+ * const { createGateway, intercept, canShip } = require("./lib/agent-firewall");
+ * 
+ * // Create gateway for session
+ * const gateway = createGateway(projectRoot);
+ * 
+ * // Intercept a change
+ * const verdict = await gateway.intercept(change, source);
+ * 
+ * // Check if can ship
+ * const allowed = await canShip(projectRoot);
+ * ```
+ * 
+ * @module agent-firewall
+ * @version 3.0.0
+ */
+
+"use strict";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORE MODULES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// Intent system
+const intent = require("./intent");
+
+// Enforcement system
+const enforcement = require("./enforcement");
+
+// Session system
+const session = require("./session");
+
+// Interception layer
+let interception;
+try {
+  interception = require("./interception");
+} catch {
+  interception = {};
+}
+
+// Integration layer
+let integration;
+try {
+  integration = require("./integration");
+} catch {
+  integration = {};
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UNIFIED EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PRIMARY API - Gateway (THE entry point for enforcement)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // Gateway creation and use
+  EnforcementGateway: enforcement.EnforcementGateway,
+  createGateway: enforcement.createGateway,
+  intercept: enforcement.intercept,
+  quickCheck: enforcement.quickCheck,
+  
+  // Change event helpers
+  buildChangeEvent: enforcement.buildChangeEvent,
+  analyzeCodeQuality: enforcement.analyzeCodeQuality,
+  classifyDomain: enforcement.classifyDomain,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // INTENT SYSTEM
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // Intent store
+  IntentStore: intent.IntentStore,
+  
+  // Intent creation and validation
+  createIntent: intent.createIntent,
+  verifyIntentIntegrity: intent.verifyIntentIntegrity,
+  isIntentExpired: intent.isIntentExpired,
+  computeIntentHash: intent.computeIntentHash,
+  
+  // Alignment checking
+  checkAlignment: intent.checkAlignment,
+  checkAlignmentBatch: intent.checkAlignmentBatch,
+  VIOLATION_CODES: intent.VIOLATION_CODES,
+  
+  // Auto-detection
+  autoDetectIntent: intent.autoDetectIntent,
+  inferIntentFromGit: intent.inferIntentFromGit,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // VERDICT SYSTEM
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // Verdict generation
+  generateVerdict: enforcement.generateVerdict,
+  generateVerdictId: enforcement.generateVerdictId,
+  
+  // Verdict verification
+  computeVerdictHash: enforcement.computeVerdictHash,
+  verifyVerdictIntegrity: enforcement.verifyVerdictIntegrity,
+  
+  // Verdict formatting
+  formatBlockMessage: enforcement.formatBlockMessage,
+  createVerdictManifest: enforcement.createVerdictManifest,
+  
+  // Legacy conversion
+  convertLegacyVerdict: enforcement.convertLegacyVerdict,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PROOF SYSTEM
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  ProofCollection: enforcement.ProofCollection,
+  determineRequiredProofs: enforcement.determineRequiredProofs,
+  PROOF_STATUS: enforcement.PROOF_STATUS,
+  PROOF_TYPE: enforcement.PROOF_TYPE,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SESSION SYSTEM
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  SessionCollector: session.SessionCollector,
+  getCollector: session.getCollector,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // INTERCEPTION LAYER
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // File system interception
+  activateFsInterceptor: interception.activateFsInterceptor,
+  deactivateFsInterceptor: interception.deactivateFsInterceptor,
+  isFsInterceptorActive: interception.isFsInterceptorActive,
+  BlockedWriteError: interception.BlockedWriteError,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // INTEGRATION LAYER (ship/packs/seal/CI)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // Ship gate
+  ShipGate: integration.ShipGate,
+  createShipGate: integration.createShipGate,
+  canShip: integration.canShip,
+  getCIStatus: integration.getCIStatus,
+  SHIP_GATE_STATUS: integration.SHIP_GATE_STATUS,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // MODE & CONSTANTS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  MODE: enforcement.MODE,
+  VERDICT: enforcement.VERDICT,
+  OBSERVATION: enforcement.OBSERVATION,
+  BLOCK_PATTERNS: enforcement.BLOCK_PATTERNS,
+  
+  // Mode configuration
+  ModeConfig: enforcement.ModeConfig,
+  formatModeBanner: enforcement.formatModeBanner,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LEGACY COMPATIBILITY
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // Orchestrator (use gateway for new code)
+  FirewallOrchestrator: enforcement.FirewallOrchestrator,
+  createOrchestrator: enforcement.createOrchestrator,
+  normalizeChangeEvent: enforcement.normalizeChangeEvent,
+  CHANGE_EVENT_TYPE: enforcement.CHANGE_EVENT_TYPE,
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SUBMODULE ACCESS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // For advanced use cases that need full submodule access
+  _modules: {
+    intent,
+    enforcement,
+    session,
+    interception,
+    integration,
+  },
+};

package/bin/runners/lib/agent-firewall/integration/index.js

@@ -0,0 +1,20 @@
+/**
+ * Agent Firewall Integration Index
+ * 
+ * Exports integration modules for ship/packs/seal/CI.
+ * 
+ * @module integration
+ */
+
+"use strict";
+
+const shipGate = require("./ship-gate");
+
+module.exports = {
+  // Ship Gate
+  ShipGate: shipGate.ShipGate,
+  createShipGate: shipGate.createShipGate,
+  canShip: shipGate.canShip,
+  getCIStatus: shipGate.getCIStatus,
+  SHIP_GATE_STATUS: shipGate.SHIP_GATE_STATUS,
+};