speclock 1.7.0 → 2.1.0

package/src/core/compliance.js

@@ -0,0 +1,291 @@
+/**
+ * SpecLock Compliance Export Engine
+ * Generates audit-ready reports for SOC 2, HIPAA, and CSV formats.
+ * Designed for enterprise compliance teams and auditors.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import { readBrain, readEvents } from "./storage.js";
+import { verifyAuditChain } from "./audit.js";
+
+const VERSION = "2.1.0";
+
+// PHI-related keywords for HIPAA filtering
+const PHI_KEYWORDS = [
+  "patient", "phi", "health", "medical", "hipaa", "ehr", "emr",
+  "diagnosis", "treatment", "prescription", "clinical", "healthcare",
+  "protected health", "health record", "medical record", "patient data",
+  "health information", "insurance", "claims", "billing",
+];
+
+// Security-related event types
+const SECURITY_EVENT_TYPES = [
+  "lock_added", "lock_removed", "decision_added",
+  "goal_updated", "init", "session_started", "session_ended",
+  "checkpoint_created", "revert_detected",
+];
+
+/**
+ * Check if text matches any PHI keywords (case-insensitive).
+ */
+function isPHIRelated(text) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  return PHI_KEYWORDS.some((kw) => lower.includes(kw));
+}
+
+/**
+ * Generate SOC 2 Type II compliance report.
+ * Covers: constraint changes, access events, change management, audit integrity.
+ */
+export function exportSOC2(root) {
+  const brain = readBrain(root);
+  if (!brain) {
+    return { error: "SpecLock not initialized. Run speclock init first." };
+  }
+
+  const events = readEvents(root, { limit: 10000 });
+  const auditResult = verifyAuditChain(root);
+  const activeLocks = (brain.specLock?.items || []).filter((l) => l.active);
+  const allLocks = brain.specLock?.items || [];
+
+  // Group events by type for analysis
+  const eventsByType = {};
+  for (const e of events) {
+    if (!eventsByType[e.type]) eventsByType[e.type] = [];
+    eventsByType[e.type].push(e);
+  }
+
+  // Calculate constraint change history
+  const constraintChanges = events
+    .filter((e) => ["lock_added", "lock_removed"].includes(e.type))
+    .map((e) => ({
+      timestamp: e.at || e.ts,
+      action: e.type === "lock_added" ? "ADDED" : "REMOVED",
+      lockId: e.lockId || e.summary?.match(/\[([^\]]+)\]/)?.[1] || "unknown",
+      text: e.lockText || e.summary || "",
+      source: e.source || "unknown",
+      eventId: e.eventId,
+      hash: e.hash || null,
+    }));
+
+  // Session history (access log)
+  const sessions = (brain.sessions?.history || []).map((s) => ({
+    tool: s.tool || "unknown",
+    startedAt: s.startedAt,
+    endedAt: s.endedAt || null,
+    summary: s.summary || "",
+  }));
+
+  // Decision audit trail
+  const decisions = (brain.decisions || []).map((d) => ({
+    id: d.id,
+    text: d.text,
+    createdAt: d.createdAt,
+    source: d.source || "unknown",
+    tags: d.tags || [],
+  }));
+
+  return {
+    report: "SOC 2 Type II — SpecLock Compliance Export",
+    version: VERSION,
+    generatedAt: new Date().toISOString(),
+    project: {
+      name: brain.project?.name || "unknown",
+      id: brain.project?.id || "unknown",
+      createdAt: brain.project?.createdAt,
+      goal: brain.goal?.text || "",
+    },
+    auditChainIntegrity: {
+      valid: auditResult.valid,
+      totalEvents: auditResult.totalEvents,
+      hashedEvents: auditResult.hashedEvents,
+      unhashedEvents: auditResult.unhashedEvents,
+      brokenAt: auditResult.brokenAt,
+      verifiedAt: auditResult.verifiedAt,
+    },
+    constraintManagement: {
+      activeConstraints: activeLocks.length,
+      totalConstraints: allLocks.length,
+      removedConstraints: allLocks.filter((l) => !l.active).length,
+      changeHistory: constraintChanges,
+    },
+    accessLog: {
+      totalSessions: sessions.length,
+      sessions,
+    },
+    decisionAuditTrail: {
+      totalDecisions: decisions.length,
+      decisions,
+    },
+    changeManagement: {
+      totalEvents: events.length,
+      eventBreakdown: Object.fromEntries(
+        Object.entries(eventsByType).map(([type, evts]) => [type, evts.length])
+      ),
+      recentChanges: (brain.state?.recentChanges || []).slice(0, 20),
+      reverts: brain.state?.reverts || [],
+    },
+    violations: {
+      total: (brain.state?.violations || []).length,
+      items: (brain.state?.violations || []).slice(0, 50),
+    },
+  };
+}
+
+/**
+ * Generate HIPAA compliance report.
+ * Filtered for PHI-related constraints, access events, and encryption status.
+ */
+export function exportHIPAA(root) {
+  const brain = readBrain(root);
+  if (!brain) {
+    return { error: "SpecLock not initialized. Run speclock init first." };
+  }
+
+  const events = readEvents(root, { limit: 10000 });
+  const auditResult = verifyAuditChain(root);
+  const allLocks = brain.specLock?.items || [];
+
+  // Filter PHI-related locks
+  const phiLocks = allLocks.filter((l) => isPHIRelated(l.text));
+  const activePhiLocks = phiLocks.filter((l) => l.active);
+
+  // Filter PHI-related events
+  const phiEvents = events.filter(
+    (e) => isPHIRelated(e.summary || "") || isPHIRelated(e.lockText || "")
+  );
+
+  // PHI-related decisions
+  const phiDecisions = (brain.decisions || []).filter((d) =>
+    isPHIRelated(d.text)
+  );
+
+  // PHI-related violations
+  const phiViolations = (brain.state?.violations || []).filter(
+    (v) => isPHIRelated(v.lockText || "") || isPHIRelated(v.action || "")
+  );
+
+  // Check encryption status
+  const encryptionEnabled = !!process.env.SPECLOCK_ENCRYPTION_KEY;
+
+  // Access controls
+  const hasAuth = !!process.env.SPECLOCK_API_KEY;
+  const hasAuditChain = auditResult.hashedEvents > 0;
+
+  return {
+    report: "HIPAA Compliance — SpecLock PHI Protection Report",
+    version: VERSION,
+    generatedAt: new Date().toISOString(),
+    project: {
+      name: brain.project?.name || "unknown",
+      id: brain.project?.id || "unknown",
+    },
+    safeguards: {
+      technicalSafeguards: {
+        auditControls: {
+          enabled: hasAuditChain,
+          chainValid: auditResult.valid,
+          totalAuditedEvents: auditResult.hashedEvents,
+          status: hasAuditChain
+            ? auditResult.valid
+              ? "COMPLIANT"
+              : "NON-COMPLIANT — audit chain broken"
+            : "PARTIAL — enable HMAC audit chain for full compliance",
+        },
+        accessControl: {
+          authEnabled: hasAuth,
+          status: hasAuth
+            ? "COMPLIANT"
+            : "NON-COMPLIANT — no API key authentication",
+        },
+        encryption: {
+          atRest: encryptionEnabled,
+          algorithm: encryptionEnabled ? "AES-256-GCM" : "none",
+          status: encryptionEnabled
+            ? "COMPLIANT"
+            : "NON-COMPLIANT — enable SPECLOCK_ENCRYPTION_KEY",
+        },
+      },
+      administrativeSafeguards: {
+        constraintEnforcement: {
+          totalPhiConstraints: phiLocks.length,
+          activePhiConstraints: activePhiLocks.length,
+          constraints: activePhiLocks.map((l) => ({
+            id: l.id,
+            text: l.text,
+            createdAt: l.createdAt,
+            source: l.source,
+          })),
+        },
+      },
+    },
+    phiProtection: {
+      constraints: phiLocks.map((l) => ({
+        id: l.id,
+        text: l.text,
+        active: l.active,
+        createdAt: l.createdAt,
+      })),
+      decisions: phiDecisions.map((d) => ({
+        id: d.id,
+        text: d.text,
+        createdAt: d.createdAt,
+      })),
+      violations: phiViolations,
+      relatedEvents: phiEvents.length,
+    },
+    auditTrail: {
+      integrity: auditResult,
+      phiEventCount: phiEvents.length,
+    },
+  };
+}
+
+/**
+ * Generate CSV export of all events.
+ * Returns a CSV string suitable for auditor spreadsheets.
+ */
+export function exportCSV(root) {
+  const events = readEvents(root, { limit: 10000 });
+
+  if (!events.length) {
+    return "timestamp,event_id,type,summary,files,hash\n";
+  }
+
+  // Reverse back to chronological order (readEvents returns newest first)
+  events.reverse();
+
+  const header = "timestamp,event_id,type,summary,files,hash";
+  const rows = events.map((e) => {
+    const timestamp = e.at || e.ts || "";
+    const eventId = e.eventId || "";
+    const type = e.type || "";
+    const summary = (e.summary || "").replace(/"/g, '""');
+    const files = (e.files || []).join("; ");
+    const hash = e.hash || "";
+    return `"${timestamp}","${eventId}","${type}","${summary}","${files}","${hash}"`;
+  });
+
+  return [header, ...rows].join("\n");
+}
+
+/**
+ * Main export function — dispatches by format.
+ */
+export function exportCompliance(root, format) {
+  switch (format) {
+    case "soc2":
+      return { format: "soc2", data: exportSOC2(root) };
+    case "hipaa":
+      return { format: "hipaa", data: exportHIPAA(root) };
+    case "csv":
+      return { format: "csv", data: exportCSV(root) };
+    default:
+      return {
+        error: `Unknown format: ${format}. Supported: soc2, hipaa, csv`,
+        supportedFormats: ["soc2", "hipaa", "csv"],
+      };
+  }
+}

package/src/core/engine.js

@@ -17,6 +17,11 @@ import {
 } from "./storage.js";
 import { hasGit, getHead, getDefaultBranch, captureDiff, getStagedFiles } from "./git.js";
 import { getTemplateNames, getTemplate } from "./templates.js";
+import { analyzeConflict } from "./semantics.js";
+import { ensureAuditKeyGitignored } from "./audit.js";
+import { verifyAuditChain } from "./audit.js";
+import { exportCompliance } from "./compliance.js";
+import { checkFeature, checkLimits, getLicenseInfo } from "./license.js";
 
 // --- Internal helpers ---
 
@@ -40,6 +45,7 @@ function writePatch(root, eventId, content) {
 
 export function ensureInit(root) {
   ensureSpeclockDirs(root);
+  try { ensureAuditKeyGitignored(root); } catch { /* non-critical */ }
   let brain = readBrain(root);
   if (!brain) {
     const gitExists = hasGit(root);
@@ -251,7 +257,8 @@ export function handleFileEvent(root, brain, type, filePath) {
   recordEvent(root, brain, event);
 }
 
-// --- Synonym groups for semantic matching ---
+// --- Legacy synonym groups (deprecated — kept for backward compatibility) ---
+// @deprecated Use analyzeConflict() from semantics.js instead
 const SYNONYM_GROUPS = [
   ["remove", "delete", "drop", "eliminate", "destroy", "kill", "purge", "wipe"],
   ["add", "create", "introduce", "insert", "new"],
@@ -270,12 +277,13 @@ const SYNONYM_GROUPS = [
   ["enable", "activate", "turn-on", "switch-on"],
 ];
 
-// Negation words that invert meaning
+// @deprecated
 const NEGATION_WORDS = ["no", "not", "never", "without", "dont", "don't", "cannot", "can't", "shouldn't", "mustn't", "avoid", "prevent", "prohibit", "forbid", "disallow"];
 
-// Destructive action words
+// @deprecated
 const DESTRUCTIVE_WORDS = ["remove", "delete", "drop", "destroy", "kill", "purge", "wipe", "break", "disable", "revert", "rollback", "undo"];
 
+// @deprecated — use analyzeConflict() from semantics.js
 function expandWithSynonyms(words) {
   const expanded = new Set(words);
   for (const word of words) {
@@ -288,17 +296,20 @@ function expandWithSynonyms(words) {
   return [...expanded];
 }
 
+// @deprecated
 function hasNegation(text) {
   const lower = text.toLowerCase();
   return NEGATION_WORDS.some((neg) => lower.includes(neg));
 }
 
+// @deprecated
 function isDestructiveAction(text) {
   const lower = text.toLowerCase();
   return DESTRUCTIVE_WORDS.some((w) => lower.includes(w));
 }
 
 // Check if a proposed action conflicts with any active SpecLock
+// v2: Uses the semantic analysis engine from semantics.js
 export function checkConflict(root, proposedAction) {
   const brain = ensureInit(root);
   const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
@@ -310,61 +321,18 @@ export function checkConflict(root, proposedAction) {
     };
   }
 
-  const actionLower = proposedAction.toLowerCase();
-  const actionWords = actionLower.split(/\s+/).filter((w) => w.length > 2);
-  const actionExpanded = expandWithSynonyms(actionWords);
-  const actionIsDestructive = isDestructiveAction(actionLower);
-
   const conflicting = [];
   for (const lock of activeLocks) {
-    const lockLower = lock.text.toLowerCase();
-    const lockWords = lockLower.split(/\s+/).filter((w) => w.length > 2);
-    const lockExpanded = expandWithSynonyms(lockWords);
-
-    // Direct keyword overlap
-    const directOverlap = actionWords.filter((w) => lockWords.includes(w));
-
-    // Synonym-expanded overlap
-    const synonymOverlap = actionExpanded.filter((w) => lockExpanded.includes(w));
-    const uniqueSynonymMatches = synonymOverlap.filter((w) => !directOverlap.includes(w));
-
-    // Negation analysis: lock says "No X" and action does X
-    const lockHasNegation = hasNegation(lockLower);
-    const actionHasNegation = hasNegation(actionLower);
-    const negationConflict = lockHasNegation && !actionHasNegation && synonymOverlap.length > 0;
-
-    // Calculate confidence score
-    let confidence = 0;
-    let reasons = [];
-
-    if (directOverlap.length > 0) {
-      confidence += directOverlap.length * 30;
-      reasons.push(`direct keyword match: ${directOverlap.join(", ")}`);
-    }
-    if (uniqueSynonymMatches.length > 0) {
-      confidence += uniqueSynonymMatches.length * 15;
-      reasons.push(`synonym match: ${uniqueSynonymMatches.join(", ")}`);
-    }
-    if (negationConflict) {
-      confidence += 40;
-      reasons.push("lock prohibits this action (negation detected)");
-    }
-    if (actionIsDestructive && synonymOverlap.length > 0) {
-      confidence += 20;
-      reasons.push("destructive action against locked constraint");
-    }
-
-    confidence = Math.min(confidence, 100);
+    const result = analyzeConflict(proposedAction, lock.text);
 
-    if (confidence >= 15) {
-      const level = confidence >= 70 ? "HIGH" : confidence >= 40 ? "MEDIUM" : "LOW";
+    if (result.isConflict) {
       conflicting.push({
         id: lock.id,
         text: lock.text,
-        matchedKeywords: [...new Set([...directOverlap, ...uniqueSynonymMatches])],
-        confidence,
-        level,
-        reasons,
+        matchedKeywords: [],
+        confidence: result.confidence,
+        level: result.level,
+        reasons: result.reasons,
       });
     }
   }
@@ -373,7 +341,7 @@ export function checkConflict(root, proposedAction) {
     return {
       hasConflict: false,
       conflictingLocks: [],
-      analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (keyword + synonym + negation analysis). Proceed with caution.`,
+      analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (semantic analysis v2). Proceed with caution.`,
     };
   }
 
@@ -406,6 +374,21 @@ export function checkConflict(root, proposedAction) {
   return result;
 }
 
+// Async version — uses LLM if available, falls back to heuristic
+export async function checkConflictAsync(root, proposedAction) {
+  // Try LLM first (if llm-checker is available)
+  try {
+    const { llmCheckConflict } = await import("./llm-checker.js");
+    const llmResult = await llmCheckConflict(root, proposedAction);
+    if (llmResult) return llmResult;
+  } catch (_) {
+    // LLM checker not available or failed — fall through to heuristic
+  }
+
+  // Fallback to heuristic
+  return checkConflict(root, proposedAction);
+}
+
 // --- Auto-lock suggestions ---
 export function suggestLocks(root) {
   const brain = ensureInit(root);
@@ -478,7 +461,7 @@ export function suggestLocks(root) {
   return { suggestions, totalLocks: brain.specLock.items.filter((l) => l.active).length };
 }
 
-// --- Drift detection ---
+// --- Drift detection (v2: uses semantic engine) ---
 export function detectDrift(root) {
   const brain = ensureInit(root);
   const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
@@ -488,29 +471,20 @@ export function detectDrift(root) {
 
   const drifts = [];
 
-  // Check recent changes against locks
+  // Check recent changes against locks using the semantic engine
   for (const change of brain.state.recentChanges) {
-    const changeLower = change.summary.toLowerCase();
-    const changeWords = changeLower.split(/\s+/).filter((w) => w.length > 2);
-    const changeExpanded = expandWithSynonyms(changeWords);
-
     for (const lock of activeLocks) {
-      const lockLower = lock.text.toLowerCase();
-      const lockWords = lockLower.split(/\s+/).filter((w) => w.length > 2);
-      const lockExpanded = expandWithSynonyms(lockWords);
-
-      const overlap = changeExpanded.filter((w) => lockExpanded.includes(w));
-      const lockHasNegation = hasNegation(lockLower);
+      const result = analyzeConflict(change.summary, lock.text);
 
-      if (overlap.length >= 2 && lockHasNegation) {
+      if (result.isConflict) {
         drifts.push({
           lockId: lock.id,
           lockText: lock.text,
           changeEventId: change.eventId,
           changeSummary: change.summary,
           changeAt: change.at,
-          matchedTerms: overlap,
-          severity: overlap.length >= 3 ? "high" : "medium",
+          matchedTerms: result.reasons,
+          severity: result.level === "HIGH" ? "high" : "medium",
         });
       }
     }
@@ -1246,3 +1220,9 @@ export function auditStagedFiles(root) {
     message,
   };
 }
+
+// --- Enterprise features (v2.1) ---
+
+export { verifyAuditChain } from "./audit.js";
+export { exportCompliance } from "./compliance.js";
+export { checkFeature, checkLimits, getLicenseInfo } from "./license.js";