speclock 2.1.1 → 3.0.0

package/src/core/tracking.js

@@ -0,0 +1,98 @@
+/**
+ * SpecLock Tracking Module
+ * Change logging, file event handling, event management.
+ * Extracted from engine.js for modularity.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import {
+  nowIso,
+  newId,
+  writeBrain,
+  appendEvent,
+  bumpEvents,
+  speclockDir,
+  addRecentChange,
+  addRevert,
+} from "./storage.js";
+import { captureDiff } from "./git.js";
+import { ensureInit } from "./memory.js";
+
+// --- Internal helpers ---
+
+function recordEvent(root, brain, event) {
+  bumpEvents(brain, event.eventId);
+  appendEvent(root, event);
+  writeBrain(root, brain);
+}
+
+function writePatch(root, eventId, content) {
+  const patchPath = path.join(
+    speclockDir(root),
+    "patches",
+    `${eventId}.patch`
+  );
+  fs.writeFileSync(patchPath, content);
+  return path.join(".speclock", "patches", `${eventId}.patch`);
+}
+
+// --- Core functions ---
+
+export function logChange(root, summary, files = []) {
+  const brain = ensureInit(root);
+  const eventId = newId("evt");
+  let patchPath = "";
+  if (brain.facts.repo.hasGit) {
+    const diff = captureDiff(root);
+    if (diff && diff.trim().length > 0) {
+      patchPath = writePatch(root, eventId, diff);
+    }
+  }
+  const event = {
+    eventId,
+    type: "manual_change",
+    at: nowIso(),
+    files,
+    summary,
+    patchPath,
+  };
+  addRecentChange(brain, {
+    eventId,
+    summary,
+    files,
+    at: event.at,
+  });
+  recordEvent(root, brain, event);
+  return { brain, eventId };
+}
+
+export function handleFileEvent(root, brain, type, filePath) {
+  const eventId = newId("evt");
+  const rel = path.relative(root, filePath);
+  let patchPath = "";
+  if (brain.facts.repo.hasGit) {
+    const diff = captureDiff(root);
+    const patchContent =
+      diff && diff.trim().length > 0 ? diff : "(no diff available)";
+    patchPath = writePatch(root, eventId, patchContent);
+  }
+  const summary = `${type.replace("_", " ")}: ${rel}`;
+  const event = {
+    eventId,
+    type,
+    at: nowIso(),
+    files: [rel],
+    summary,
+    patchPath,
+  };
+  addRecentChange(brain, {
+    eventId,
+    summary,
+    files: [rel],
+    at: event.at,
+  });
+  recordEvent(root, brain, event);
+}

package/src/mcp/http-server.js

@@ -30,6 +30,11 @@ import {
   auditStagedFiles,
   verifyAuditChain,
   exportCompliance,
+  enforceConflictCheck,
+  setEnforcementMode,
+  overrideLock,
+  getOverrideHistory,
+  semanticAudit,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -46,9 +51,21 @@ import {
   createTag,
   getDiffSummary,
 } from "../core/git.js";
+import {
+  isAuthEnabled,
+  validateApiKey,
+  checkPermission,
+  createApiKey,
+  rotateApiKey,
+  revokeApiKey,
+  listApiKeys,
+  enableAuth,
+  disableAuth,
+  TOOL_PERMISSIONS,
+} from "../core/auth.js";
 
 const PROJECT_ROOT = process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
-const VERSION = "2.1.1";
+const VERSION = "3.0.0";
 const AUTHOR = "Sandeep Roy";
 const START_TIME = Date.now();
 
@@ -219,11 +236,14 @@ function createSpecLockServer() {
     return { content: [{ type: "text", text: events.length ? JSON.stringify(events, null, 2) : "No matching events." }] };
   });
 
-  // Tool 12: speclock_check_conflict
-  server.tool("speclock_check_conflict", "Check if a proposed action conflicts with any active SpecLock.", { proposedAction: z.string().min(1).describe("Description of the action") }, async ({ proposedAction }) => {
+  // Tool 12: speclock_check_conflict (v2.5: uses enforcer)
+  server.tool("speclock_check_conflict", "Check if a proposed action conflicts with any active SpecLock. In hard mode, blocks above threshold.", { proposedAction: z.string().min(1).describe("Description of the action") }, async ({ proposedAction }) => {
     ensureInit(PROJECT_ROOT);
-    const result = await checkConflictAsync(PROJECT_ROOT, proposedAction);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    const result = enforceConflictCheck(PROJECT_ROOT, proposedAction);
+    if (result.blocked) {
+      return { content: [{ type: "text", text: result.analysis }], isError: true };
+    }
+    return { content: [{ type: "text", text: result.analysis }] };
   });
 
   // Tool 13: speclock_session_briefing
@@ -354,6 +374,35 @@ function createSpecLockServer() {
     return { content: [{ type: "text", text: output }] };
   });
 
+  // Tool 25: speclock_set_enforcement (v2.5)
+  server.tool("speclock_set_enforcement", "Set enforcement mode: advisory (warn) or hard (block).", { mode: z.enum(["advisory", "hard"]).describe("Enforcement mode"), blockThreshold: z.number().int().min(0).max(100).optional().default(70).describe("Block threshold %") }, async ({ mode, blockThreshold }) => {
+    const result = setEnforcementMode(PROJECT_ROOT, mode, { blockThreshold });
+    if (!result.success) return { content: [{ type: "text", text: result.error }], isError: true };
+    return { content: [{ type: "text", text: `Enforcement: ${mode} (threshold: ${result.config.blockThreshold}%)` }] };
+  });
+
+  // Tool 26: speclock_override_lock (v2.5)
+  server.tool("speclock_override_lock", "Override a lock with justification. Logged to audit trail.", { lockId: z.string().min(1), action: z.string().min(1), reason: z.string().min(1) }, async ({ lockId, action, reason }) => {
+    const result = overrideLock(PROJECT_ROOT, lockId, action, reason);
+    if (!result.success) return { content: [{ type: "text", text: result.error }], isError: true };
+    const msg = result.escalated ? `\n${result.escalationMessage}` : "";
+    return { content: [{ type: "text", text: `Override: "${result.lockText}" (${result.overrideCount}x)${msg}` }] };
+  });
+
+  // Tool 27: speclock_semantic_audit (v2.5)
+  server.tool("speclock_semantic_audit", "Semantic pre-commit: analyzes code changes vs locks.", {}, async () => {
+    const result = semanticAudit(PROJECT_ROOT);
+    return { content: [{ type: "text", text: result.message }], isError: result.blocked || false };
+  });
+
+  // Tool 28: speclock_override_history (v2.5)
+  server.tool("speclock_override_history", "Show lock override history.", { lockId: z.string().optional() }, async ({ lockId }) => {
+    const result = getOverrideHistory(PROJECT_ROOT, lockId);
+    if (result.total === 0) return { content: [{ type: "text", text: "No overrides recorded." }] };
+    const lines = result.overrides.map(o => `[${o.at.substring(0,19)}] "${o.lockText}" — ${o.reason}`).join("\n");
+    return { content: [{ type: "text", text: `Overrides (${result.total}):\n${lines}` }] };
+  });
+
   return server;
 }
 
@@ -366,6 +415,16 @@ app.options("*", (req, res) => {
   res.writeHead(204).end();
 });
 
+// --- Auth middleware helper ---
+function authenticateRequest(req) {
+  if (!isAuthEnabled(PROJECT_ROOT)) {
+    return { valid: true, role: "admin", authEnabled: false };
+  }
+  const authHeader = req.headers["authorization"] || "";
+  const rawKey = authHeader.startsWith("Bearer ") ? authHeader.slice(7).trim() : "";
+  return validateApiKey(PROJECT_ROOT, rawKey);
+}
+
 app.post("/mcp", async (req, res) => {
   setCorsHeaders(res);
 
@@ -389,6 +448,28 @@ app.post("/mcp", async (req, res) => {
     });
   }
 
+  // Authentication (v3.0)
+  const auth = authenticateRequest(req);
+  if (!auth.valid) {
+    return res.status(401).json({
+      jsonrpc: "2.0",
+      error: { code: -32000, message: auth.error || "Authentication required." },
+      id: null,
+    });
+  }
+
+  // RBAC check — extract tool name from JSON-RPC body for permission check
+  if (auth.authEnabled && req.body && req.body.method === "tools/call") {
+    const toolName = req.body.params?.name;
+    if (toolName && !checkPermission(auth.role, toolName)) {
+      return res.status(403).json({
+        jsonrpc: "2.0",
+        error: { code: -32000, message: `Permission denied. Role "${auth.role}" cannot access "${toolName}". Required: ${TOOL_PERMISSIONS[toolName] || "admin"}` },
+        id: req.body.id || null,
+      });
+    }
+  }
+
   const server = createSpecLockServer();
   try {
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
@@ -406,6 +487,51 @@ app.post("/mcp", async (req, res) => {
   }
 });
 
+// --- Auth management endpoint (v3.0) ---
+app.post("/auth", async (req, res) => {
+  setCorsHeaders(res);
+  const auth = authenticateRequest(req);
+
+  const { action } = req.body || {};
+
+  // Creating the first key doesn't require auth (bootstrap)
+  if (action === "create-key" && !isAuthEnabled(PROJECT_ROOT)) {
+    const { role, name } = req.body;
+    const result = createApiKey(PROJECT_ROOT, role || "admin", name || "");
+    return res.json(result);
+  }
+
+  // All other auth actions require admin role
+  if (auth.authEnabled && (!auth.valid || auth.role !== "admin")) {
+    return res.status(auth.valid ? 403 : 401).json({
+      error: auth.valid ? "Admin role required for auth management." : auth.error,
+    });
+  }
+
+  switch (action) {
+    case "create-key": {
+      const { role, name } = req.body;
+      return res.json(createApiKey(PROJECT_ROOT, role || "developer", name || ""));
+    }
+    case "rotate-key": {
+      const { keyId } = req.body;
+      return res.json(rotateApiKey(PROJECT_ROOT, keyId));
+    }
+    case "revoke-key": {
+      const { keyId, reason } = req.body;
+      return res.json(revokeApiKey(PROJECT_ROOT, keyId, reason || "manual"));
+    }
+    case "list-keys":
+      return res.json(listApiKeys(PROJECT_ROOT));
+    case "enable":
+      return res.json(enableAuth(PROJECT_ROOT));
+    case "disable":
+      return res.json(disableAuth(PROJECT_ROOT));
+    default:
+      return res.status(400).json({ error: `Unknown auth action: "${action}". Valid: create-key, rotate-key, revoke-key, list-keys, enable, disable` });
+  }
+});
+
 app.get("/mcp", async (req, res) => {
   setCorsHeaders(res);
   res.writeHead(405).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed." }, id: null }));
@@ -431,8 +557,9 @@ app.get("/health", (req, res) => {
     status: "healthy",
     version: VERSION,
     uptime: Math.floor((Date.now() - START_TIME) / 1000),
-    tools: 24,
+    tools: 28,
     auditChain: auditStatus,
+    authEnabled: isAuthEnabled(PROJECT_ROOT),
     rateLimit: { limit: RATE_LIMIT, windowMs: RATE_WINDOW_MS },
   });
 });
@@ -445,7 +572,7 @@ app.get("/", (req, res) => {
     version: VERSION,
     author: AUTHOR,
     description: "AI Continuity Engine with enterprise audit, compliance, and enforcement",
-    tools: 24,
+    tools: 28,
     mcp_endpoint: "/mcp",
     health_endpoint: "/health",
     npm: "https://www.npmjs.com/package/speclock",

package/src/mcp/server.js

@@ -27,6 +27,12 @@ import {
   exportCompliance,
   checkLimits,
   getLicenseInfo,
+  enforceConflictCheck,
+  setEnforcementMode,
+  overrideLock,
+  getOverrideHistory,
+  getEnforcementConfig,
+  semanticAudit,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -43,6 +49,29 @@ import {
   createTag,
   getDiffSummary,
 } from "../core/git.js";
+import {
+  isAuthEnabled,
+  validateApiKey,
+  checkPermission,
+} from "../core/auth.js";
+
+// --- Auth via env var (v3.0) ---
+function getAuthRole() {
+  if (!isAuthEnabled(PROJECT_ROOT)) return "admin";
+  const key = process.env.SPECLOCK_API_KEY;
+  if (!key) return "admin"; // No key env var = local use, allow all
+  const result = validateApiKey(PROJECT_ROOT, key);
+  return result.valid ? result.role : null;
+}
+
+function requirePermission(toolName) {
+  const role = getAuthRole();
+  if (!role) return { allowed: false, error: "Invalid SPECLOCK_API_KEY." };
+  if (!checkPermission(role, toolName)) {
+    return { allowed: false, error: `Permission denied. Role "${role}" cannot access "${toolName}".` };
+  }
+  return { allowed: true, role };
+}
 
 // --- Project root resolution ---
 function parseArgs(argv) {
@@ -61,7 +90,7 @@ const PROJECT_ROOT =
   args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
 
 // --- MCP Server ---
-const VERSION = "2.1.1";
+const VERSION = "3.0.0";
 const AUTHOR = "Sandeep Roy";
 
 const server = new McpServer(
@@ -421,10 +450,10 @@ server.tool(
 // CONTINUITY PROTECTION TOOLS
 // ========================================
 
-// Tool 12: speclock_check_conflict
+// Tool 12: speclock_check_conflict (v2.5: uses enforcer — hard mode returns isError)
 server.tool(
   "speclock_check_conflict",
-  "Check if a proposed action conflicts with any active SpecLock. Use before making significant changes.",
+  "Check if a proposed action conflicts with any active SpecLock. Use before making significant changes. In hard enforcement mode, conflicts above the threshold will BLOCK the action (isError: true).",
   {
     proposedAction: z
       .string()
@@ -432,7 +461,28 @@ server.tool(
       .describe("Description of the action you plan to take"),
   },
   async ({ proposedAction }) => {
-    const result = await checkConflictAsync(PROJECT_ROOT, proposedAction);
+    // Try LLM-enhanced check first, fall back to heuristic enforcer
+    let result;
+    try {
+      const { llmCheckConflict } = await import("../core/llm-checker.js");
+      const llmResult = await llmCheckConflict(PROJECT_ROOT, proposedAction);
+      if (llmResult) {
+        result = llmResult;
+      }
+    } catch (_) {}
+
+    if (!result) {
+      result = enforceConflictCheck(PROJECT_ROOT, proposedAction);
+    }
+
+    // In hard mode with blocking conflict, return isError: true
+    if (result.blocked) {
+      return {
+        content: [{ type: "text", text: result.analysis }],
+        isError: true,
+      };
+    }
+
     return {
       content: [{ type: "text", text: result.analysis }],
     };
@@ -958,6 +1008,158 @@ server.tool(
   }
 );
 
+// ========================================
+// HARD ENFORCEMENT TOOLS (v2.5)
+// ========================================
+
+// Tool 25: speclock_set_enforcement
+server.tool(
+  "speclock_set_enforcement",
+  "Set the enforcement mode for this project. 'advisory' (default) warns about conflicts. 'hard' blocks actions that violate locks above the confidence threshold — the AI cannot proceed.",
+  {
+    mode: z
+      .enum(["advisory", "hard"])
+      .describe("Enforcement mode: advisory (warn) or hard (block)"),
+    blockThreshold: z
+      .number()
+      .int()
+      .min(0)
+      .max(100)
+      .optional()
+      .default(70)
+      .describe("Minimum confidence % to block in hard mode (default: 70)"),
+    allowOverride: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Whether lock overrides are permitted"),
+  },
+  async ({ mode, blockThreshold, allowOverride }) => {
+    const result = setEnforcementMode(PROJECT_ROOT, mode, { blockThreshold, allowOverride });
+    if (!result.success) {
+      return {
+        content: [{ type: "text", text: result.error }],
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Enforcement mode set to **${mode}**. Threshold: ${result.config.blockThreshold}%. Overrides: ${result.config.allowOverride ? "allowed" : "disabled"}.`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool 26: speclock_override_lock
+server.tool(
+  "speclock_override_lock",
+  "Override a lock for a specific action. Requires a reason which is logged to the audit trail. Use when a locked action must proceed with justification. Triggers escalation after repeated overrides.",
+  {
+    lockId: z.string().min(1).describe("The lock ID to override"),
+    action: z.string().min(1).describe("The action that conflicts with the lock"),
+    reason: z.string().min(1).describe("Justification for the override"),
+  },
+  async ({ lockId, action, reason }) => {
+    const result = overrideLock(PROJECT_ROOT, lockId, action, reason);
+    if (!result.success) {
+      return {
+        content: [{ type: "text", text: result.error }],
+        isError: true,
+      };
+    }
+
+    const parts = [
+      `Lock overridden: "${result.lockText}"`,
+      `Override count: ${result.overrideCount}`,
+      `Reason: ${reason}`,
+    ];
+
+    if (result.escalated) {
+      parts.push("", result.escalationMessage);
+    }
+
+    return {
+      content: [{ type: "text", text: parts.join("\n") }],
+    };
+  }
+);
+
+// Tool 27: speclock_semantic_audit
+server.tool(
+  "speclock_semantic_audit",
+  "Run semantic pre-commit audit. Parses the staged git diff, analyzes actual code changes against active locks using semantic analysis. Much more powerful than filename-only audit — catches violations in code content.",
+  {},
+  async () => {
+    const result = semanticAudit(PROJECT_ROOT);
+
+    if (result.passed) {
+      return {
+        content: [{ type: "text", text: result.message }],
+      };
+    }
+
+    const formatted = result.violations
+      .map((v) => {
+        const lines = [`- [${v.level}] **${v.file}** (confidence: ${v.confidence}%)`];
+        lines.push(`  Lock: "${v.lockText}"`);
+        lines.push(`  Reason: ${v.reason}`);
+        if (v.addedLines) lines.push(`  Changes: +${v.addedLines} / -${v.removedLines} lines`);
+        return lines.join("\n");
+      })
+      .join("\n\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## Semantic Audit Result\n\nMode: ${result.mode} | Threshold: ${result.threshold}%\n\n${formatted}\n\n${result.message}`,
+        },
+      ],
+      isError: result.blocked || false,
+    };
+  }
+);
+
+// Tool 28: speclock_override_history
+server.tool(
+  "speclock_override_history",
+  "Get the history of lock overrides. Shows which locks have been overridden, by whom, and the reasons given. Useful for audit review and identifying locks that may need updating.",
+  {
+    lockId: z
+      .string()
+      .optional()
+      .describe("Filter by specific lock ID. Omit to see all overrides."),
+  },
+  async ({ lockId }) => {
+    const result = getOverrideHistory(PROJECT_ROOT, lockId);
+
+    if (result.total === 0) {
+      return {
+        content: [{ type: "text", text: "No overrides recorded." }],
+      };
+    }
+
+    const formatted = result.overrides
+      .map(
+        (o) =>
+          `- [${o.at.substring(0, 19)}] Lock: "${o.lockText}" (${o.lockId})\n  Action: ${o.action}\n  Reason: ${o.reason}`
+      )
+      .join("\n\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## Override History (${result.total})\n\n${formatted}`,
+        },
+      ],
+    };
+  }
+);
+
 // --- Smithery sandbox export ---
 export default function createSandboxServer() {
   return server;