speclock 2.1.1 → 3.0.0

package/src/core/crypto.js

@@ -0,0 +1,158 @@
+/**
+ * SpecLock Encrypted Storage
+ * AES-256-GCM encryption for brain.json and events.log at rest.
+ *
+ * Key derivation: PBKDF2 from SPECLOCK_ENCRYPTION_KEY env var
+ * Transparent: encrypt on write, decrypt on read
+ * Format: Base64(IV:AuthTag:CipherText) per line/file
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import crypto from "crypto";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 16;
+const AUTH_TAG_LENGTH = 16;
+const SALT = "speclock-v3-salt"; // Static salt (key is already strong from env)
+const ITERATIONS = 100000;
+const KEY_LENGTH = 32;
+const ENCRYPTED_MARKER = "SPECLOCK_ENCRYPTED:";
+
+// --- Key Derivation ---
+
+let _derivedKey = null;
+
+/**
+ * Check if encryption is enabled (env var set).
+ */
+export function isEncryptionEnabled() {
+  return !!process.env.SPECLOCK_ENCRYPTION_KEY;
+}
+
+/**
+ * Derive a 256-bit key from the master password.
+ */
+export function deriveKey(masterKey) {
+  if (!masterKey) {
+    throw new Error("SPECLOCK_ENCRYPTION_KEY is required for encryption.");
+  }
+  return crypto.pbkdf2Sync(masterKey, SALT, ITERATIONS, KEY_LENGTH, "sha512");
+}
+
+/**
+ * Get or derive the encryption key from env var.
+ */
+function getKey() {
+  if (_derivedKey) return _derivedKey;
+  const masterKey = process.env.SPECLOCK_ENCRYPTION_KEY;
+  if (!masterKey) {
+    throw new Error("SPECLOCK_ENCRYPTION_KEY environment variable is not set.");
+  }
+  _derivedKey = deriveKey(masterKey);
+  return _derivedKey;
+}
+
+/**
+ * Clear cached key (for testing).
+ */
+export function clearKeyCache() {
+  _derivedKey = null;
+}
+
+// --- Encrypt / Decrypt ---
+
+/**
+ * Encrypt a string. Returns: SPECLOCK_ENCRYPTED:<base64(iv:tag:ciphertext)>
+ */
+export function encrypt(plaintext) {
+  const key = getKey();
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+
+  let encrypted = cipher.update(plaintext, "utf-8");
+  encrypted = Buffer.concat([encrypted, cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  // Pack: IV + AuthTag + Ciphertext
+  const packed = Buffer.concat([iv, authTag, encrypted]);
+  return ENCRYPTED_MARKER + packed.toString("base64");
+}
+
+/**
+ * Decrypt a string. Input: SPECLOCK_ENCRYPTED:<base64(iv:tag:ciphertext)>
+ */
+export function decrypt(ciphertext) {
+  if (!ciphertext.startsWith(ENCRYPTED_MARKER)) {
+    // Not encrypted — return as-is (backward compatible with plaintext)
+    return ciphertext;
+  }
+
+  const key = getKey();
+  const packed = Buffer.from(ciphertext.slice(ENCRYPTED_MARKER.length), "base64");
+
+  if (packed.length < IV_LENGTH + AUTH_TAG_LENGTH + 1) {
+    throw new Error("Invalid encrypted data: too short.");
+  }
+
+  const iv = packed.subarray(0, IV_LENGTH);
+  const authTag = packed.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+  const encrypted = packed.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+
+  let decrypted = decipher.update(encrypted);
+  decrypted = Buffer.concat([decrypted, decipher.final()]);
+  return decrypted.toString("utf-8");
+}
+
+/**
+ * Check if a string is encrypted.
+ */
+export function isEncrypted(data) {
+  return typeof data === "string" && data.startsWith(ENCRYPTED_MARKER);
+}
+
+// --- File-level helpers ---
+
+/**
+ * Encrypt a JSON object for storage.
+ */
+export function encryptJSON(obj) {
+  const json = JSON.stringify(obj, null, 2);
+  return encrypt(json);
+}
+
+/**
+ * Decrypt and parse a JSON string.
+ */
+export function decryptJSON(data) {
+  const json = decrypt(data);
+  return JSON.parse(json);
+}
+
+/**
+ * Encrypt each line of an events log (JSONL format).
+ * Each line is encrypted independently.
+ */
+export function encryptLines(text) {
+  if (!text || !text.trim()) return text;
+  const lines = text.trim().split("\n");
+  return lines.map(line => {
+    if (!line.trim()) return line;
+    return encrypt(line);
+  }).join("\n") + "\n";
+}
+
+/**
+ * Decrypt each line of an encrypted events log.
+ */
+export function decryptLines(text) {
+  if (!text || !text.trim()) return text;
+  const lines = text.trim().split("\n");
+  return lines.map(line => {
+    if (!line.trim()) return line;
+    return decrypt(line);
+  }).join("\n") + "\n";
+}

package/src/core/enforcer.js

@@ -0,0 +1,314 @@
+/**
+ * SpecLock Hard Enforcement Engine
+ * Moves from advisory-only to blocking enforcement.
+ *
+ * Modes:
+ * - "advisory" (default): Returns warnings, AI decides what to do
+ * - "hard": Returns isError:true in MCP, exit code 1 in CLI, 409 in HTTP
+ *
+ * Features:
+ * - Configurable block threshold (default 70%)
+ * - Override mechanism with reason logging to audit trail
+ * - Escalation: 3+ overrides on same lock → auto-note for review
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import {
+  readBrain,
+  writeBrain,
+  appendEvent,
+  bumpEvents,
+  newId,
+  nowIso,
+  addViolation,
+} from "./storage.js";
+import { analyzeConflict } from "./semantics.js";
+
+// --- Enforcement config helpers ---
+
+/**
+ * Get enforcement config from brain, with defaults.
+ */
+export function getEnforcementConfig(brain) {
+  const defaults = {
+    mode: "advisory",       // "advisory" | "hard"
+    blockThreshold: 70,     // minimum confidence % to block in hard mode
+    allowOverride: true,    // whether overrides are permitted
+    escalationLimit: 3,     // overrides before auto-note
+  };
+
+  if (!brain.enforcement) return { ...defaults };
+
+  return {
+    ...defaults,
+    ...brain.enforcement,
+  };
+}
+
+/**
+ * Set enforcement mode on a project.
+ */
+export function setEnforcementMode(root, mode, options = {}) {
+  const brain = readBrain(root);
+  if (!brain) {
+    return { success: false, error: "SpecLock not initialized." };
+  }
+
+  if (mode !== "advisory" && mode !== "hard") {
+    return { success: false, error: `Invalid mode: "${mode}". Must be "advisory" or "hard".` };
+  }
+
+  if (!brain.enforcement) {
+    brain.enforcement = {};
+  }
+
+  brain.enforcement.mode = mode;
+  if (options.blockThreshold !== undefined) {
+    brain.enforcement.blockThreshold = Math.max(0, Math.min(100, options.blockThreshold));
+  }
+  if (options.allowOverride !== undefined) {
+    brain.enforcement.allowOverride = !!options.allowOverride;
+  }
+  if (options.escalationLimit !== undefined) {
+    brain.enforcement.escalationLimit = Math.max(1, options.escalationLimit);
+  }
+
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "enforcement_mode_changed",
+    at: nowIso(),
+    files: [],
+    summary: `Enforcement mode set to: ${mode}${options.blockThreshold ? ` (threshold: ${options.blockThreshold}%)` : ""}`,
+    patchPath: "",
+  };
+  bumpEvents(brain, eventId);
+  appendEvent(root, event);
+  writeBrain(root, brain);
+
+  return {
+    success: true,
+    mode,
+    config: getEnforcementConfig(brain),
+  };
+}
+
+/**
+ * Enforce a conflict check — returns enriched result with enforcement metadata.
+ * This wraps the existing checkConflict logic with hard/advisory behavior.
+ */
+export function enforceConflictCheck(root, proposedAction) {
+  const brain = readBrain(root);
+  if (!brain) {
+    return {
+      hasConflict: false,
+      blocked: false,
+      mode: "advisory",
+      conflictingLocks: [],
+      analysis: "SpecLock not initialized. No enforcement.",
+    };
+  }
+
+  const config = getEnforcementConfig(brain);
+  const activeLocks = (brain.specLock?.items || []).filter((l) => l.active !== false);
+
+  if (activeLocks.length === 0) {
+    return {
+      hasConflict: false,
+      blocked: false,
+      mode: config.mode,
+      conflictingLocks: [],
+      analysis: "No active locks. No constraints to check against.",
+    };
+  }
+
+  // Run semantic analysis against all active locks
+  const conflicting = [];
+  for (const lock of activeLocks) {
+    const result = analyzeConflict(proposedAction, lock.text);
+    if (result.isConflict) {
+      conflicting.push({
+        id: lock.id,
+        text: lock.text,
+        confidence: result.confidence,
+        level: result.level,
+        reasons: result.reasons,
+      });
+    }
+  }
+
+  if (conflicting.length === 0) {
+    return {
+      hasConflict: false,
+      blocked: false,
+      mode: config.mode,
+      conflictingLocks: [],
+      analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (semantic analysis v2). Proceed with caution.`,
+    };
+  }
+
+  // Sort by confidence descending
+  conflicting.sort((a, b) => b.confidence - a.confidence);
+
+  // Determine if this should be BLOCKED (hard mode + above threshold)
+  const topConfidence = conflicting[0].confidence;
+  const meetsThreshold = topConfidence >= config.blockThreshold;
+  const blocked = config.mode === "hard" && meetsThreshold;
+
+  const details = conflicting
+    .map(
+      (c) =>
+        `- [${c.level}] "${c.text}" (confidence: ${c.confidence}%)\n  Reasons: ${c.reasons.join("; ")}`
+    )
+    .join("\n");
+
+  // Record violation
+  addViolation(brain, {
+    at: nowIso(),
+    action: proposedAction,
+    locks: conflicting.map((c) => ({ id: c.id, text: c.text, confidence: c.confidence, level: c.level })),
+    topLevel: conflicting[0].level,
+    topConfidence,
+    enforced: blocked,
+    mode: config.mode,
+  });
+  writeBrain(root, brain);
+
+  const modeLabel = blocked
+    ? "BLOCKED — Hard enforcement active. This action cannot proceed."
+    : "WARNING — Advisory mode. Review before proceeding.";
+
+  return {
+    hasConflict: true,
+    blocked,
+    mode: config.mode,
+    threshold: config.blockThreshold,
+    topConfidence,
+    conflictingLocks: conflicting,
+    analysis: `${modeLabel}\n\nConflict with ${conflicting.length} lock(s):\n${details}`,
+  };
+}
+
+/**
+ * Override a lock for a specific action, with a reason.
+ * Logged to audit trail. Triggers escalation if overridden too many times.
+ */
+export function overrideLock(root, lockId, action, reason) {
+  const brain = readBrain(root);
+  if (!brain) {
+    return { success: false, error: "SpecLock not initialized." };
+  }
+
+  const config = getEnforcementConfig(brain);
+  if (!config.allowOverride) {
+    return { success: false, error: "Overrides are disabled for this project." };
+  }
+
+  const lock = (brain.specLock?.items || []).find((l) => l.id === lockId);
+  if (!lock) {
+    return { success: false, error: `Lock not found: ${lockId}` };
+  }
+  if (!lock.active) {
+    return { success: false, error: `Lock is already inactive: ${lockId}` };
+  }
+
+  // Initialize overrides tracking on the lock
+  if (!lock.overrides) lock.overrides = [];
+  lock.overrides.push({
+    at: nowIso(),
+    action,
+    reason,
+  });
+
+  // Record override event in audit trail
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "lock_overridden",
+    at: nowIso(),
+    files: [],
+    summary: `Lock overridden: "${lock.text.substring(0, 60)}" — Reason: ${reason.substring(0, 100)}`,
+    patchPath: "",
+    meta: { lockId, action, reason },
+  };
+  bumpEvents(brain, eventId);
+  appendEvent(root, event);
+
+  // Check for escalation
+  let escalated = false;
+  const overrideCount = lock.overrides.length;
+  if (overrideCount >= config.escalationLimit) {
+    escalated = true;
+
+    // Auto-create a note flagging this for review
+    const noteId = newId("note");
+    brain.notes.unshift({
+      id: noteId,
+      text: `ESCALATION: Lock "${lock.text}" has been overridden ${overrideCount} times. Review whether this lock is still appropriate or if it should be removed.`,
+      createdAt: nowIso(),
+      pinned: true,
+    });
+
+    const noteEventId = newId("evt");
+    const noteEvent = {
+      eventId: noteEventId,
+      type: "note_added",
+      at: nowIso(),
+      files: [],
+      summary: `Escalation note: Lock "${lock.text.substring(0, 40)}" overridden ${overrideCount} times`,
+      patchPath: "",
+    };
+    bumpEvents(brain, noteEventId);
+    appendEvent(root, noteEvent);
+  }
+
+  writeBrain(root, brain);
+
+  return {
+    success: true,
+    lockId,
+    lockText: lock.text,
+    overrideCount,
+    escalated,
+    escalationMessage: escalated
+      ? `WARNING: This lock has been overridden ${overrideCount} times (limit: ${config.escalationLimit}). An escalation note has been created for review.`
+      : null,
+  };
+}
+
+/**
+ * Get override history for a specific lock or all locks.
+ */
+export function getOverrideHistory(root, lockId = null) {
+  const brain = readBrain(root);
+  if (!brain) {
+    return { overrides: [], total: 0 };
+  }
+
+  const locks = (brain.specLock?.items || []).filter((l) => {
+    if (lockId) return l.id === lockId;
+    return l.overrides && l.overrides.length > 0;
+  });
+
+  const overrides = [];
+  for (const lock of locks) {
+    if (!lock.overrides) continue;
+    for (const ov of lock.overrides) {
+      overrides.push({
+        lockId: lock.id,
+        lockText: lock.text,
+        lockActive: lock.active,
+        ...ov,
+      });
+    }
+  }
+
+  // Sort by date descending
+  overrides.sort((a, b) => (b.at > a.at ? 1 : -1));
+
+  return {
+    overrides,
+    total: overrides.length,
+  };
+}