speclock 2.1.1 → 3.0.0

package/README.md

@@ -58,6 +58,9 @@ No other tool does this. Not Claude's native memory. Not Mem0. Not CLAUDE.md fil
 | Git-aware (checkpoints, rollback) | No | No | No | **Yes** |
 | Drift detection | No | No | No | **Yes — scans changes against locks** |
 | CI/CD integration | No | No | No | **Yes — GitHub Actions** |
+| **Hard enforcement (block violations)** | No | No | No | **Yes — hard mode blocks above threshold** |
+| **API Key Auth + RBAC** | No | No | No | **Yes** |
+| **Encrypted Storage (AES-256)** | No | No | No | **Yes** |
 | Multi-agent timeline | No | No | No | **Yes** |
 | Cross-platform | Claude only | MCP only | Tool-specific | **Universal (MCP + npm)** |
 
@@ -192,10 +195,10 @@ Result:  NO CONFLICT (confidence: 7%)
 | Mode | Platforms | How It Works |
 |------|-----------|--------------|
 | **MCP Remote** | Lovable, bolt.diy, Base44 | Connect via URL — no install needed |
-| **MCP Local** | Claude Code, Cursor, Windsurf, Cline | `npx speclock serve` — 24 tools via MCP |
+| **MCP Local** | Claude Code, Cursor, Windsurf, Cline | `npx speclock serve` — 28 tools via MCP |
 | **npm File-Based** | Bolt.new, Aider, Rocket.new | `npx speclock setup` — AI reads SPECLOCK.md + uses CLI |
 
-## 24 MCP Tools
+## 28 MCP Tools
 
 ### Memory Management
 | Tool | Purpose |
@@ -249,6 +252,14 @@ Result:  NO CONFLICT (confidence: 7%)
 | `speclock_verify_audit` | Verify HMAC audit chain integrity — tamper detection |
 | `speclock_export_compliance` | Generate SOC 2 / HIPAA / CSV compliance reports |
 
+### Hard Enforcement (v2.5)
+| Tool | Purpose |
+|------|---------|
+| `speclock_set_enforcement` | Set enforcement mode: advisory (warn) or hard (block) |
+| `speclock_override_lock` | Override a lock with justification — logged to audit trail |
+| `speclock_semantic_audit` | Semantic pre-commit: analyze code changes vs locks |
+| `speclock_override_history` | View lock override history for audit review |
+
 ## Auto-Guard: Locks That Actually Work
 
 When you add a lock, SpecLock **automatically finds and guards related files**:
@@ -317,6 +328,12 @@ speclock audit-verify                  # Verify HMAC audit chain integrity
 speclock export --format <soc2|hipaa|csv>  # Compliance export
 speclock license                       # Show license tier and usage
 
+# Hard Enforcement (v2.5)
+speclock enforce <advisory|hard>       # Set enforcement mode
+speclock override <lockId> <reason>    # Override a lock with justification
+speclock overrides [--lock <id>]       # Show override history
+speclock audit-semantic                # Semantic pre-commit audit
+
 # Other
 speclock status                        # Show brain summary
 speclock serve [--project <path>]      # Start MCP server
@@ -372,6 +389,38 @@ SOC 2 reports include: constraint change history, access logs, decision audit tr
 ```
 Audits changed files against locks, posts PR comments, fails workflow on violations.
 
+## Hard Enforcement (v2.5)
+
+### Advisory vs Hard Mode
+```
+Advisory mode (default): AI gets a warning, decides what to do
+Hard mode:               AI is BLOCKED — cannot proceed (MCP returns isError: true)
+```
+
+- **Block threshold**: Configurable (default 70%). Only HIGH confidence conflicts block.
+- **Override mechanism**: `speclock_override_lock` with a reason (logged to audit trail)
+- **Escalation**: Lock overridden 3+ times → auto-creates a review note
+- **Semantic pre-commit**: Parses actual git diff content, runs semantic analysis against locks
+
+## Security & Access Control (v3.0)
+
+### API Key Authentication
+SHA-256 hashed keys stored server-side. HTTP transport uses `Authorization: Bearer <key>` headers. MCP transport authenticates via the `SPECLOCK_API_KEY` environment variable. Keys are never stored in plaintext.
+
+### RBAC (4 Roles)
+| Role | Permissions |
+|------|-------------|
+| **viewer** | Read-only access to context, locks, decisions, and events |
+| **developer** | Read + override locks with a documented reason |
+| **architect** | Read + write (add/remove locks, decisions) + override |
+| **admin** | Full access — manage keys, roles, enforcement settings, and all operations |
+
+### AES-256-GCM Encryption
+Transparent encrypt-on-write / decrypt-on-read for `brain.json` and `events.log`. Encryption key is derived via PBKDF2 from the `SPECLOCK_ENCRYPTION_KEY` environment variable. Authenticated encryption (GCM) ensures both confidentiality and integrity. **HIPAA 2026 compliant.**
+
+### Test Coverage
+**300 tests passing** (up from 186 in v2.5). Full coverage for authentication, authorization, encryption, semantic detection, and audit chain integrity.
+
 ---
 
 ## Architecture
@@ -382,14 +431,15 @@ Audits changed files against locks, posts PR comments, fails workflow on violati
 └──────────────┬──────────────────┬────────────────────┘
                │                  │
      MCP Protocol          File-Based (npm)
-    (24 tool calls)      (reads SPECLOCK.md +
+    (28 tool calls)      (reads SPECLOCK.md +
                         .speclock/context/latest.md,
                          runs CLI commands)
                │                  │
 ┌──────────────▼──────────────────▼────────────────────┐
 │              SpecLock Core Engine                      │
 │  Memory | Tracking | Enforcement | Git | Intelligence │
-│  Audit  | Compliance | License                        │
+│  Audit  | Compliance | License | Auth | RBAC          │
+│  AES-256-GCM Encryption (brain.json, events.log)      │
 └──────────────────────┬───────────────────────────────┘
                        │
                 .speclock/
@@ -419,4 +469,4 @@ MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-*SpecLock v2.1.0 — Semantic conflict detection + enterprise audit & compliance. 100% detection, 0% false positives. HMAC audit chain, SOC 2/HIPAA exports. Because remembering isn't enough — AI needs to respect boundaries.*
+*SpecLock v3.0.0 — Semantic conflict detection + enterprise audit & compliance. 100% detection, 0% false positives. HMAC audit chain, SOC 2/HIPAA exports. Hard enforcement mode. API Key Auth + RBAC. AES-256-GCM encrypted storage. 300 tests passing. Because remembering isn't enough — AI needs to respect boundaries.*

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speclock",
-  "version": "2.1.1",
-  "description": "AI constraint engine with semantic conflict detection, HMAC audit chain, SOC 2/HIPAA compliance exports. 100% detection, 0% false positives. 24 MCP tools + CLI. Enterprise-ready memory + enforcement.",
+  "version": "3.0.0",
+  "description": "AI constraint engine with API key auth, RBAC, AES-256-GCM encryption, hard enforcement, semantic pre-commit, HMAC audit chain, SOC 2/HIPAA compliance. 100% detection, 0% false positives. 28 MCP tools + CLI. Enterprise-ready.",
   "type": "module",
   "main": "src/mcp/server.js",
   "bin": {
@@ -36,7 +36,12 @@
     "hipaa",
     "compliance",
     "audit-trail",
-    "hmac"
+    "hmac",
+    "encryption",
+    "aes-256",
+    "api-key",
+    "authentication",
+    "rbac"
   ],
   "author": "Sandeep Roy (https://github.com/sgroy10)",
   "license": "MIT",
@@ -64,6 +69,7 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "esbuild": "^0.27.3"
+    "esbuild": "^0.27.3",
+    "jest": "^30.2.0"
   }
 }

package/src/cli/index.js

@@ -23,10 +23,26 @@ import {
   verifyAuditChain,
   exportCompliance,
   getLicenseInfo,
+  enforceConflictCheck,
+  setEnforcementMode,
+  overrideLock,
+  getOverrideHistory,
+  getEnforcementConfig,
+  semanticAudit,
 } from "../core/engine.js";
 import { generateContext } from "../core/context.js";
 import { readBrain } from "../core/storage.js";
 import { installHook, removeHook } from "../core/hooks.js";
+import {
+  isAuthEnabled,
+  enableAuth,
+  disableAuth,
+  createApiKey,
+  rotateApiKey,
+  revokeApiKey,
+  listApiKeys,
+} from "../core/auth.js";
+import { isEncryptionEnabled } from "../core/crypto.js";
 
 // --- Argument parsing ---
 
@@ -82,7 +98,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v2.1.1 — AI Constraint Engine (Enterprise)
+SpecLock v3.0.0 — AI Constraint Engine (Auth + RBAC + Encryption + Hard Enforcement)
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
@@ -105,7 +121,11 @@ Commands:
   hook install                    Install git pre-commit hook
   hook remove                     Remove git pre-commit hook
   audit                           Audit staged files against locks
+  audit-semantic                  Semantic audit: analyze code changes vs locks
   audit-verify                    Verify HMAC audit chain integrity
+  enforce <advisory|hard>         Set enforcement mode (advisory=warn, hard=block)
+  override <lockId> <reason>      Override a lock with justification
+  overrides [--lock <id>]         Show override history
   export --format <soc2|hipaa|csv>  Export compliance report
   license                         Show license tier and usage info
   context                         Generate and print context pack
@@ -126,10 +146,22 @@ Options:
 
 Templates: nextjs, react, express, supabase, stripe, security-hardened
 
+Security (v3.0):
+  auth status                     Show auth status and active keys
+  auth create-key --role <role>   Create API key (viewer/developer/architect/admin)
+  auth rotate-key <keyId>         Rotate an API key
+  auth revoke-key <keyId>         Revoke an API key
+  auth list-keys                  List all API keys
+  auth enable                     Enable API key authentication
+  auth disable                    Disable authentication
+  encrypt [status]                Show encryption status
+
 Enterprise:
   SPECLOCK_AUDIT_SECRET           HMAC secret for audit chain (env var)
   SPECLOCK_LICENSE_KEY            License key for Pro/Enterprise features
   SPECLOCK_LLM_KEY                API key for LLM-powered conflict detection
+  SPECLOCK_ENCRYPTION_KEY         Master key for AES-256-GCM encryption
+  SPECLOCK_API_KEY                API key for MCP server auth
 
 Examples:
   npx speclock setup --goal "Build PawPalace pet shop" --template nextjs
@@ -176,6 +208,8 @@ function showStatus(root) {
   }
 
   console.log(`Recent changes: ${brain.state.recentChanges.length}`);
+  console.log(`Auth: ${isAuthEnabled(root) ? "enabled" : "disabled"}`);
+  console.log(`Encryption: ${isEncryptionEnabled() ? "enabled (AES-256-GCM)" : "disabled"}`);
   console.log("");
 }
 
@@ -385,10 +419,12 @@ Tip: When starting a new chat, tell the AI:
       console.error('Usage: speclock check "what you plan to do"');
       process.exit(1);
     }
-    const result = checkConflict(root, text);
+    const result = enforceConflictCheck(root, text);
     if (result.hasConflict) {
-      console.log(`\nCONFLICT DETECTED`);
+      console.log(`\n${result.blocked ? "BLOCKED" : "CONFLICT DETECTED"}`);
       console.log("=".repeat(50));
+      console.log(`Mode: ${result.mode} | Threshold: ${result.threshold}%`);
+      console.log("");
       for (const lock of result.conflictingLocks) {
         console.log(`  [${lock.level}] "${lock.text}"`);
         console.log(`  Confidence: ${lock.confidence}%`);
@@ -400,6 +436,9 @@ Tip: When starting a new chat, tell the AI:
         console.log("");
       }
       console.log(result.analysis);
+      if (result.blocked) {
+        process.exit(1);
+      }
     } else {
       console.log(`No conflicts found. Safe to proceed with: "${text}"`);
     }
@@ -674,6 +713,211 @@ Tip: When starting a new chat, tell the AI:
     return;
   }
 
+  // --- ENFORCE (v2.5) ---
+  if (cmd === "enforce") {
+    const mode = args[0];
+    if (!mode || (mode !== "advisory" && mode !== "hard")) {
+      console.error("Usage: speclock enforce <advisory|hard> [--threshold 70]");
+      process.exit(1);
+    }
+    const flags = parseFlags(args.slice(1));
+    const options = {};
+    if (flags.threshold) options.blockThreshold = parseInt(flags.threshold, 10);
+    if (flags.override !== undefined) options.allowOverride = flags.override !== "false";
+    const result = setEnforcementMode(root, mode, options);
+    if (!result.success) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    console.log(`\nEnforcement mode: ${result.mode.toUpperCase()}`);
+    console.log(`Block threshold: ${result.config.blockThreshold}%`);
+    console.log(`Overrides: ${result.config.allowOverride ? "allowed" : "disabled"}`);
+    if (result.mode === "hard") {
+      console.log(`\nHard mode active — conflicts above ${result.config.blockThreshold}% confidence will BLOCK actions.`);
+    }
+    return;
+  }
+
+  // --- OVERRIDE (v2.5) ---
+  if (cmd === "override") {
+    const lockId = args[0];
+    const reason = args.slice(1).join(" ");
+    if (!lockId || !reason) {
+      console.error("Usage: speclock override <lockId> <reason>");
+      process.exit(1);
+    }
+    const result = overrideLock(root, lockId, "(CLI override)", reason);
+    if (!result.success) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    console.log(`Lock overridden: "${result.lockText}"`);
+    console.log(`Override count: ${result.overrideCount}`);
+    if (result.escalated) {
+      console.log(`\n${result.escalationMessage}`);
+    }
+    return;
+  }
+
+  // --- OVERRIDES (v2.5) ---
+  if (cmd === "overrides") {
+    const flags = parseFlags(args);
+    const result = getOverrideHistory(root, flags.lock || null);
+    if (result.total === 0) {
+      console.log("No overrides recorded.");
+      return;
+    }
+    console.log(`\nOverride History (${result.total})`);
+    console.log("=".repeat(50));
+    for (const o of result.overrides) {
+      console.log(`[${o.at.substring(0, 19)}] Lock: "${o.lockText}"`);
+      console.log(`  Action: ${o.action}`);
+      console.log(`  Reason: ${o.reason}`);
+      console.log("");
+    }
+    return;
+  }
+
+  // --- AUDIT-SEMANTIC (v2.5) ---
+  if (cmd === "audit-semantic") {
+    const result = semanticAudit(root);
+    console.log(`\nSemantic Pre-Commit Audit`);
+    console.log("=".repeat(50));
+    console.log(`Mode: ${result.mode} | Threshold: ${result.threshold}%`);
+    console.log(`Files analyzed: ${result.filesChecked}`);
+    console.log(`Active locks: ${result.activeLocks}`);
+    console.log(`Violations: ${result.violations.length}`);
+    if (result.violations.length > 0) {
+      console.log("");
+      for (const v of result.violations) {
+        console.log(`  [${v.level}] ${v.file} (confidence: ${v.confidence}%)`);
+        console.log(`    Lock: "${v.lockText}"`);
+        console.log(`    Reason: ${v.reason}`);
+        if (v.addedLines !== undefined) {
+          console.log(`    Changes: +${v.addedLines} / -${v.removedLines} lines`);
+        }
+      }
+    }
+    console.log(`\n${result.message}`);
+    process.exit(result.blocked ? 1 : 0);
+  }
+
+  // --- AUTH (v3.0) ---
+  if (cmd === "auth") {
+    const sub = args[0];
+    if (!sub || sub === "status") {
+      const enabled = isAuthEnabled(root);
+      console.log(`\nAuth Status: ${enabled ? "ENABLED" : "DISABLED"}`);
+      if (enabled) {
+        const keys = listApiKeys(root);
+        const active = keys.keys.filter(k => k.active);
+        console.log(`Active keys: ${active.length}`);
+        for (const k of active) {
+          console.log(`  ${k.id} — ${k.name} (${k.role}) — last used: ${k.lastUsed || "never"}`);
+        }
+      } else {
+        console.log("Run 'speclock auth create-key --role admin' to enable auth.");
+      }
+      return;
+    }
+    if (sub === "create-key") {
+      const flags = parseFlags(args.slice(1));
+      const role = flags.role || "developer";
+      const name = flags.name || flags._.join(" ") || "";
+      const result = createApiKey(root, role, name);
+      if (!result.success) {
+        console.error(result.error);
+        process.exit(1);
+      }
+      console.log(`\nAPI Key Created`);
+      console.log("=".repeat(50));
+      console.log(`Key ID:  ${result.keyId}`);
+      console.log(`Role:    ${result.role}`);
+      console.log(`Name:    ${result.name}`);
+      console.log(`\nRaw Key: ${result.rawKey}`);
+      console.log(`\nSave this key — it CANNOT be retrieved later.`);
+      console.log(`\nUsage:`);
+      console.log(`  HTTP:  Authorization: Bearer ${result.rawKey}`);
+      console.log(`  MCP:   Set SPECLOCK_API_KEY=${result.rawKey} in MCP config`);
+      return;
+    }
+    if (sub === "rotate-key") {
+      const keyId = args[1];
+      if (!keyId) {
+        console.error("Usage: speclock auth rotate-key <keyId>");
+        process.exit(1);
+      }
+      const result = rotateApiKey(root, keyId);
+      if (!result.success) {
+        console.error(result.error);
+        process.exit(1);
+      }
+      console.log(`\nKey Rotated`);
+      console.log(`Old key: ${result.oldKeyId} (revoked)`);
+      console.log(`New key: ${result.newKeyId}`);
+      console.log(`Raw Key: ${result.rawKey}`);
+      console.log(`\nSave this key — it CANNOT be retrieved later.`);
+      return;
+    }
+    if (sub === "revoke-key") {
+      const keyId = args[1];
+      if (!keyId) {
+        console.error("Usage: speclock auth revoke-key <keyId>");
+        process.exit(1);
+      }
+      const reason = args.slice(2).join(" ") || "manual";
+      const result = revokeApiKey(root, keyId, reason);
+      if (!result.success) {
+        console.error(result.error);
+        process.exit(1);
+      }
+      console.log(`Key revoked: ${result.keyId} (${result.name}, ${result.role})`);
+      return;
+    }
+    if (sub === "list-keys") {
+      const result = listApiKeys(root);
+      console.log(`\nAPI Keys (auth ${result.enabled ? "enabled" : "disabled"}):`);
+      console.log("=".repeat(50));
+      if (result.keys.length === 0) {
+        console.log("  No keys configured.");
+      } else {
+        for (const k of result.keys) {
+          const status = k.active ? "active" : `revoked (${k.revokedAt?.substring(0, 10) || "unknown"})`;
+          console.log(`  ${k.id} — ${k.name} (${k.role}) [${status}]`);
+        }
+      }
+      return;
+    }
+    if (sub === "enable") {
+      enableAuth(root);
+      console.log("Auth enabled. API keys are now required for HTTP access.");
+      return;
+    }
+    if (sub === "disable") {
+      disableAuth(root);
+      console.log("Auth disabled. All operations allowed without keys.");
+      return;
+    }
+    console.error("Usage: speclock auth <create-key|rotate-key|revoke-key|list-keys|enable|disable|status>");
+    process.exit(1);
+  }
+
+  // --- ENCRYPT STATUS (v3.0) ---
+  if (cmd === "encrypt") {
+    const sub = args[0];
+    if (sub === "status" || !sub) {
+      const enabled = isEncryptionEnabled();
+      console.log(`\nEncryption: ${enabled ? "ENABLED (AES-256-GCM)" : "DISABLED"}`);
+      if (!enabled) {
+        console.log("Set SPECLOCK_ENCRYPTION_KEY env var to enable encryption.");
+        console.log("All data will be encrypted at rest (brain.json + events.log).");
+      }
+      return;
+    }
+    console.error("Usage: speclock encrypt [status]");
+    process.exit(1);
+  }
+
   // --- STATUS ---
   if (cmd === "status") {
     showStatus(root);