speclock 2.1.1 → 3.0.0

package/src/core/auth.js

@@ -0,0 +1,341 @@
+/**
+ * SpecLock API Key Authentication
+ * Provides API key generation, validation, rotation, and revocation.
+ * Keys are SHA-256 hashed before storage — raw keys never stored.
+ *
+ * Storage: .speclock/auth.json (gitignored)
+ * Key format: sl_key_<random hex>
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+
+const AUTH_FILE = "auth.json";
+const KEY_PREFIX = "sl_key_";
+
+// --- RBAC Role Definitions ---
+
+export const ROLES = {
+  viewer: {
+    name: "viewer",
+    description: "Read-only access to context, events, and status",
+    permissions: ["read"],
+  },
+  developer: {
+    name: "developer",
+    description: "Read access + can override locks with reason",
+    permissions: ["read", "override"],
+  },
+  architect: {
+    name: "architect",
+    description: "Read + write locks, decisions, goals, notes",
+    permissions: ["read", "write", "override"],
+  },
+  admin: {
+    name: "admin",
+    description: "Full access including auth management and enforcement config",
+    permissions: ["read", "write", "override", "admin"],
+  },
+};
+
+// Tool → required permission mapping
+export const TOOL_PERMISSIONS = {
+  // Read-only tools
+  speclock_init: "read",
+  speclock_get_context: "read",
+  speclock_get_changes: "read",
+  speclock_get_events: "read",
+  speclock_session_briefing: "read",
+  speclock_repo_status: "read",
+  speclock_suggest_locks: "read",
+  speclock_detect_drift: "read",
+  speclock_health: "read",
+  speclock_report: "read",
+  speclock_verify_audit: "read",
+  speclock_export_compliance: "read",
+  speclock_override_history: "read",
+  speclock_semantic_audit: "read",
+
+  // Write tools
+  speclock_set_goal: "write",
+  speclock_add_lock: "write",
+  speclock_remove_lock: "write",
+  speclock_add_decision: "write",
+  speclock_add_note: "write",
+  speclock_set_deploy_facts: "write",
+  speclock_log_change: "write",
+  speclock_check_conflict: "read",
+  speclock_session_summary: "write",
+  speclock_checkpoint: "write",
+  speclock_apply_template: "write",
+  speclock_audit: "read",
+
+  // Override tools
+  speclock_override_lock: "override",
+
+  // Admin tools
+  speclock_set_enforcement: "admin",
+};
+
+// --- Path helpers ---
+
+function authPath(root) {
+  return path.join(root, ".speclock", AUTH_FILE);
+}
+
+// --- Auth store ---
+
+function readAuthStore(root) {
+  const p = authPath(root);
+  if (!fs.existsSync(p)) {
+    return { enabled: false, keys: [] };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return { enabled: false, keys: [] };
+  }
+}
+
+function writeAuthStore(root, store) {
+  const p = authPath(root);
+  fs.writeFileSync(p, JSON.stringify(store, null, 2));
+}
+
+function hashKey(rawKey) {
+  return crypto.createHash("sha256").update(rawKey).digest("hex");
+}
+
+function generateRawKey() {
+  return KEY_PREFIX + crypto.randomBytes(24).toString("hex");
+}
+
+// --- Gitignore auth.json ---
+
+export function ensureAuthGitignored(root) {
+  const giPath = path.join(root, ".speclock", ".gitignore");
+  let content = "";
+  if (fs.existsSync(giPath)) {
+    content = fs.readFileSync(giPath, "utf-8");
+  }
+  if (!content.includes(AUTH_FILE)) {
+    const line = content.endsWith("\n") || content === "" ? AUTH_FILE + "\n" : "\n" + AUTH_FILE + "\n";
+    fs.appendFileSync(giPath, line);
+  }
+}
+
+// --- Public API ---
+
+/**
+ * Check if auth is enabled for this project.
+ */
+export function isAuthEnabled(root) {
+  const store = readAuthStore(root);
+  return store.enabled === true && store.keys.length > 0;
+}
+
+/**
+ * Enable authentication for this project.
+ */
+export function enableAuth(root) {
+  const store = readAuthStore(root);
+  store.enabled = true;
+  writeAuthStore(root, store);
+  ensureAuthGitignored(root);
+  return { success: true };
+}
+
+/**
+ * Disable authentication (all operations allowed).
+ */
+export function disableAuth(root) {
+  const store = readAuthStore(root);
+  store.enabled = false;
+  writeAuthStore(root, store);
+  return { success: true };
+}
+
+/**
+ * Create a new API key with a role and optional name.
+ * Returns the raw key (only shown once).
+ */
+export function createApiKey(root, role, name = "") {
+  if (!ROLES[role]) {
+    return { success: false, error: `Invalid role: "${role}". Valid roles: ${Object.keys(ROLES).join(", ")}` };
+  }
+
+  const store = readAuthStore(root);
+  const rawKey = generateRawKey();
+  const keyHash = hashKey(rawKey);
+  const keyId = "key_" + crypto.randomBytes(4).toString("hex");
+
+  store.keys.push({
+    id: keyId,
+    name: name || `${role}-${keyId}`,
+    hash: keyHash,
+    role,
+    createdAt: new Date().toISOString(),
+    lastUsed: null,
+    active: true,
+  });
+
+  if (!store.enabled) {
+    store.enabled = true;
+  }
+
+  writeAuthStore(root, store);
+  ensureAuthGitignored(root);
+
+  return {
+    success: true,
+    keyId,
+    rawKey,
+    role,
+    name: name || `${role}-${keyId}`,
+    message: "Save this key — it cannot be retrieved later.",
+  };
+}
+
+/**
+ * Validate an API key. Returns the key record if valid.
+ */
+export function validateApiKey(root, rawKey) {
+  const store = readAuthStore(root);
+
+  if (!store.enabled) {
+    // Auth not enabled — allow everything (backward compatible)
+    return { valid: true, role: "admin", authEnabled: false };
+  }
+
+  if (!rawKey) {
+    return { valid: false, error: "API key required. Auth is enabled for this project." };
+  }
+
+  const keyHash = hashKey(rawKey);
+  const keyRecord = store.keys.find(k => k.hash === keyHash && k.active);
+
+  if (!keyRecord) {
+    return { valid: false, error: "Invalid or revoked API key." };
+  }
+
+  // Update last used
+  keyRecord.lastUsed = new Date().toISOString();
+  writeAuthStore(root, store);
+
+  return {
+    valid: true,
+    keyId: keyRecord.id,
+    role: keyRecord.role,
+    name: keyRecord.name,
+    authEnabled: true,
+  };
+}
+
+/**
+ * Check if a role has permission for a specific tool/action.
+ */
+export function checkPermission(role, toolName) {
+  const roleConfig = ROLES[role];
+  if (!roleConfig) return false;
+
+  // Admin has all permissions
+  if (role === "admin") return true;
+
+  const requiredPermission = TOOL_PERMISSIONS[toolName];
+  if (!requiredPermission) {
+    // Unknown tool — default to admin-only
+    return role === "admin";
+  }
+
+  return roleConfig.permissions.includes(requiredPermission);
+}
+
+/**
+ * Rotate an API key — revoke old, create new with same role and name.
+ */
+export function rotateApiKey(root, keyId) {
+  const store = readAuthStore(root);
+  const keyRecord = store.keys.find(k => k.id === keyId && k.active);
+
+  if (!keyRecord) {
+    return { success: false, error: `Active key not found: ${keyId}` };
+  }
+
+  // Revoke old key
+  keyRecord.active = false;
+  keyRecord.revokedAt = new Date().toISOString();
+  keyRecord.revokeReason = "rotated";
+
+  // Create new key with same role/name
+  const rawKey = generateRawKey();
+  const newKeyHash = hashKey(rawKey);
+  const newKeyId = "key_" + crypto.randomBytes(4).toString("hex");
+
+  store.keys.push({
+    id: newKeyId,
+    name: keyRecord.name,
+    hash: newKeyHash,
+    role: keyRecord.role,
+    createdAt: new Date().toISOString(),
+    lastUsed: null,
+    active: true,
+    rotatedFrom: keyId,
+  });
+
+  writeAuthStore(root, store);
+
+  return {
+    success: true,
+    oldKeyId: keyId,
+    newKeyId,
+    rawKey,
+    role: keyRecord.role,
+    message: "Key rotated. Save the new key — it cannot be retrieved later.",
+  };
+}
+
+/**
+ * Revoke an API key.
+ */
+export function revokeApiKey(root, keyId, reason = "manual") {
+  const store = readAuthStore(root);
+  const keyRecord = store.keys.find(k => k.id === keyId && k.active);
+
+  if (!keyRecord) {
+    return { success: false, error: `Active key not found: ${keyId}` };
+  }
+
+  keyRecord.active = false;
+  keyRecord.revokedAt = new Date().toISOString();
+  keyRecord.revokeReason = reason;
+  writeAuthStore(root, store);
+
+  return {
+    success: true,
+    keyId,
+    name: keyRecord.name,
+    role: keyRecord.role,
+  };
+}
+
+/**
+ * List all API keys (hashes hidden).
+ */
+export function listApiKeys(root) {
+  const store = readAuthStore(root);
+  return {
+    enabled: store.enabled,
+    keys: store.keys.map(k => ({
+      id: k.id,
+      name: k.name,
+      role: k.role,
+      active: k.active,
+      createdAt: k.createdAt,
+      lastUsed: k.lastUsed,
+      revokedAt: k.revokedAt || null,
+    })),
+  };
+}

package/src/core/compliance.js

@@ -9,7 +9,7 @@
 import { readBrain, readEvents } from "./storage.js";
 import { verifyAuditChain } from "./audit.js";
 
-const VERSION = "2.1.1";
+const VERSION = "3.0.0";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [

package/src/core/conflict.js

@@ -0,0 +1,363 @@
+/**
+ * SpecLock Conflict Detection Module
+ * Conflict checking, drift detection, lock suggestions, audit.
+ * Extracted from engine.js for modularity.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import {
+  nowIso,
+  readBrain,
+  writeBrain,
+  readEvents,
+  addViolation,
+} from "./storage.js";
+import { getStagedFiles } from "./git.js";
+import { analyzeConflict } from "./semantics.js";
+import { ensureInit } from "./memory.js";
+
+// --- Legacy helpers (kept for pre-commit audit backward compat) ---
+
+const NEGATION_WORDS = ["no", "not", "never", "without", "dont", "don't", "cannot", "can't", "shouldn't", "mustn't", "avoid", "prevent", "prohibit", "forbid", "disallow"];
+
+function hasNegation(text) {
+  const lower = text.toLowerCase();
+  return NEGATION_WORDS.some((neg) => lower.includes(neg));
+}
+
+const FILE_KEYWORD_PATTERNS = [
+  { keywords: ["auth", "authentication", "login", "signup", "signin", "sign-in", "sign-up"], patterns: ["**/Auth*", "**/auth*", "**/Login*", "**/login*", "**/SignUp*", "**/signup*", "**/SignIn*", "**/signin*", "**/*Auth*", "**/*auth*"] },
+  { keywords: ["database", "db", "supabase", "firebase", "mongo", "postgres", "sql", "prisma"], patterns: ["**/supabase*", "**/firebase*", "**/database*", "**/db.*", "**/db/**", "**/prisma/**", "**/*Client*", "**/*client*"] },
+  { keywords: ["payment", "pay", "stripe", "billing", "checkout", "subscription"], patterns: ["**/payment*", "**/Payment*", "**/pay*", "**/Pay*", "**/stripe*", "**/Stripe*", "**/billing*", "**/Billing*", "**/checkout*", "**/Checkout*"] },
+  { keywords: ["api", "endpoint", "route", "routes"], patterns: ["**/api/**", "**/routes/**", "**/endpoints/**"] },
+  { keywords: ["config", "configuration", "settings", "env"], patterns: ["**/config*", "**/Config*", "**/settings*", "**/Settings*"] },
+];
+
+function patternMatchesFile(pattern, filePath) {
+  const clean = pattern.replace(/\\/g, "/");
+  const fileLower = filePath.toLowerCase();
+  const patternLower = clean.toLowerCase();
+  const namePattern = patternLower.replace(/^\*\*\//, "");
+  if (!namePattern.includes("/")) {
+    const fileName = fileLower.split("/").pop();
+    const regex = new RegExp("^" + namePattern.replace(/\*/g, ".*") + "$");
+    if (regex.test(fileName)) return true;
+    const corePattern = namePattern.replace(/\*/g, "");
+    if (corePattern.length > 2 && fileName.includes(corePattern)) return true;
+  }
+  const regex = new RegExp("^" + patternLower.replace(/\*\*\//g, "(.*/)?").replace(/\*/g, "[^/]*") + "$");
+  return regex.test(fileLower);
+}
+
+const GUARD_TAG = "SPECLOCK-GUARD";
+
+// --- Core functions ---
+
+export function checkConflict(root, proposedAction) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+  if (activeLocks.length === 0) {
+    return {
+      hasConflict: false,
+      conflictingLocks: [],
+      analysis: "No active locks. No constraints to check against.",
+    };
+  }
+
+  const conflicting = [];
+  for (const lock of activeLocks) {
+    const result = analyzeConflict(proposedAction, lock.text);
+    if (result.isConflict) {
+      conflicting.push({
+        id: lock.id,
+        text: lock.text,
+        matchedKeywords: [],
+        confidence: result.confidence,
+        level: result.level,
+        reasons: result.reasons,
+      });
+    }
+  }
+
+  if (conflicting.length === 0) {
+    return {
+      hasConflict: false,
+      conflictingLocks: [],
+      analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (semantic analysis v2). Proceed with caution.`,
+    };
+  }
+
+  conflicting.sort((a, b) => b.confidence - a.confidence);
+
+  const details = conflicting
+    .map(
+      (c) =>
+        `- [${c.level}] "${c.text}" (confidence: ${c.confidence}%)\n  Reasons: ${c.reasons.join("; ")}`
+    )
+    .join("\n");
+
+  const result = {
+    hasConflict: true,
+    conflictingLocks: conflicting,
+    analysis: `Potential conflict with ${conflicting.length} lock(s):\n${details}\nReview before proceeding.`,
+  };
+
+  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: conflicting[0].confidence,
+  });
+  writeBrain(root, brain);
+
+  return result;
+}
+
+export async function checkConflictAsync(root, proposedAction) {
+  try {
+    const { llmCheckConflict } = await import("./llm-checker.js");
+    const llmResult = await llmCheckConflict(root, proposedAction);
+    if (llmResult) return llmResult;
+  } catch (_) {
+    // LLM checker not available — fall through
+  }
+  return checkConflict(root, proposedAction);
+}
+
+export function suggestLocks(root) {
+  const brain = ensureInit(root);
+  const suggestions = [];
+
+  for (const dec of brain.decisions) {
+    const lower = dec.text.toLowerCase();
+    if (/\b(always|must|only|exclusively|never|required)\b/.test(lower)) {
+      suggestions.push({
+        text: dec.text,
+        source: "decision",
+        sourceId: dec.id,
+        reason: `Decision contains strong commitment language — consider promoting to a lock`,
+      });
+    }
+  }
+
+  for (const note of brain.notes) {
+    const lower = note.text.toLowerCase();
+    if (/\b(never|must not|do not|don't|avoid|prohibit|forbidden)\b/.test(lower)) {
+      suggestions.push({
+        text: note.text,
+        source: "note",
+        sourceId: note.id,
+        reason: `Note contains prohibitive language — consider promoting to a lock`,
+      });
+    }
+  }
+
+  const existingLockTexts = brain.specLock.items
+    .filter((l) => l.active)
+    .map((l) => l.text.toLowerCase());
+
+  const commonPatterns = [
+    { keyword: "api", suggestion: "No breaking changes to public API" },
+    { keyword: "database", suggestion: "No destructive database migrations without backup" },
+    { keyword: "deploy", suggestion: "All deployments must pass CI checks" },
+    { keyword: "security", suggestion: "No secrets or credentials in source code" },
+    { keyword: "test", suggestion: "No merging without passing tests" },
+  ];
+
+  const allText = [
+    brain.goal.text,
+    ...brain.decisions.map((d) => d.text),
+    ...brain.notes.map((n) => n.text),
+  ].join(" ").toLowerCase();
+
+  for (const pattern of commonPatterns) {
+    if (allText.includes(pattern.keyword)) {
+      const alreadyLocked = existingLockTexts.some((t) =>
+        t.includes(pattern.keyword)
+      );
+      if (!alreadyLocked) {
+        suggestions.push({
+          text: pattern.suggestion,
+          source: "pattern",
+          sourceId: null,
+          reason: `Project mentions "${pattern.keyword}" but has no lock protecting it`,
+        });
+      }
+    }
+  }
+
+  return { suggestions, totalLocks: brain.specLock.items.filter((l) => l.active).length };
+}
+
+export function detectDrift(root) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+  if (activeLocks.length === 0) {
+    return { drifts: [], status: "no_locks", message: "No active locks to check against." };
+  }
+
+  const drifts = [];
+
+  for (const change of brain.state.recentChanges) {
+    for (const lock of activeLocks) {
+      const result = analyzeConflict(change.summary, lock.text);
+      if (result.isConflict) {
+        drifts.push({
+          lockId: lock.id,
+          lockText: lock.text,
+          changeEventId: change.eventId,
+          changeSummary: change.summary,
+          changeAt: change.at,
+          matchedTerms: result.reasons,
+          severity: result.level === "HIGH" ? "high" : "medium",
+        });
+      }
+    }
+  }
+
+  for (const revert of brain.state.reverts) {
+    drifts.push({
+      lockId: null,
+      lockText: "(git revert detected)",
+      changeEventId: revert.eventId,
+      changeSummary: `Git ${revert.kind} to ${revert.target.substring(0, 12)}`,
+      changeAt: revert.at,
+      matchedTerms: ["revert"],
+      severity: "high",
+    });
+  }
+
+  const status = drifts.length === 0 ? "clean" : "drift_detected";
+  const message = drifts.length === 0
+    ? `All clear. ${activeLocks.length} lock(s) checked against ${brain.state.recentChanges.length} recent change(s). No drift detected.`
+    : `WARNING: ${drifts.length} potential drift(s) detected. Review immediately.`;
+
+  return { drifts, status, message };
+}
+
+export function generateReport(root) {
+  const brain = ensureInit(root);
+  const violations = brain.state.violations || [];
+
+  if (violations.length === 0) {
+    return {
+      totalViolations: 0,
+      violationsByLock: {},
+      mostTestedLocks: [],
+      recentViolations: [],
+      summary: "No violations recorded yet. SpecLock is watching.",
+    };
+  }
+
+  const byLock = {};
+  for (const v of violations) {
+    for (const lock of v.locks) {
+      if (!byLock[lock.text]) {
+        byLock[lock.text] = { count: 0, lockId: lock.id, text: lock.text };
+      }
+      byLock[lock.text].count++;
+    }
+  }
+
+  const mostTested = Object.values(byLock).sort((a, b) => b.count - a.count);
+  const recent = violations.slice(0, 10).map((v) => ({
+    at: v.at,
+    action: v.action,
+    topLevel: v.topLevel,
+    topConfidence: v.topConfidence,
+    lockCount: v.locks.length,
+  }));
+
+  const oldest = violations[violations.length - 1];
+  const newest = violations[0];
+
+  return {
+    totalViolations: violations.length,
+    timeRange: { from: oldest.at, to: newest.at },
+    violationsByLock: byLock,
+    mostTestedLocks: mostTested.slice(0, 5),
+    recentViolations: recent,
+    summary: `SpecLock blocked ${violations.length} violation(s). Most tested lock: "${mostTested[0].text}" (${mostTested[0].count} blocks).`,
+  };
+}
+
+export function auditStagedFiles(root) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+
+  if (activeLocks.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: 0, message: "No active locks. Audit passed." };
+  }
+
+  const stagedFiles = getStagedFiles(root);
+  if (stagedFiles.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: activeLocks.length, message: "No staged files. Audit passed." };
+  }
+
+  const violations = [];
+
+  for (const file of stagedFiles) {
+    const fullPath = path.join(root, file);
+    if (fs.existsSync(fullPath)) {
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        if (content.includes(GUARD_TAG)) {
+          violations.push({
+            file,
+            reason: "File has SPECLOCK-GUARD header — it is locked and must not be modified",
+            lockText: "(file-level guard)",
+            severity: "HIGH",
+          });
+          continue;
+        }
+      } catch (_) {}
+    }
+
+    const fileLower = file.toLowerCase();
+    for (const lock of activeLocks) {
+      const lockLower = lock.text.toLowerCase();
+      const lockHasNegation = hasNegation(lockLower);
+      if (!lockHasNegation) continue;
+
+      for (const group of FILE_KEYWORD_PATTERNS) {
+        const lockMatchesKeyword = group.keywords.some((kw) => lockLower.includes(kw));
+        if (!lockMatchesKeyword) continue;
+
+        const fileMatchesPattern = group.patterns.some((pattern) => patternMatchesFile(pattern, fileLower) || patternMatchesFile(pattern, fileLower.split("/").pop()));
+        if (fileMatchesPattern) {
+          violations.push({
+            file,
+            reason: `File matches lock keyword pattern`,
+            lockText: lock.text,
+            severity: "MEDIUM",
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  const seen = new Set();
+  const unique = violations.filter((v) => {
+    if (seen.has(v.file)) return false;
+    seen.add(v.file);
+    return true;
+  });
+
+  const passed = unique.length === 0;
+  const message = passed
+    ? `Audit passed. ${stagedFiles.length} file(s) checked against ${activeLocks.length} lock(s).`
+    : `AUDIT FAILED: ${unique.length} violation(s) in ${stagedFiles.length} staged file(s).`;
+
+  return {
+    passed,
+    violations: unique,
+    checkedFiles: stagedFiles.length,
+    activeLocks: activeLocks.length,
+    message,
+  };
+}