speclock 3.0.0 → 3.5.0

package/README.md

@@ -61,6 +61,10 @@ No other tool does this. Not Claude's native memory. Not Mem0. Not CLAUDE.md fil
 | **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** |
+| **Policy-as-Code DSL** | No | No | No | **Yes — declarative YAML rules** |
+| **OAuth/OIDC SSO** | No | No | No | **Yes — Okta, Azure AD, Auth0** |
+| **Admin Dashboard** | No | No | No | **Yes — real-time web UI** |
+| **Telemetry & Analytics** | No | No | No | **Yes — opt-in usage insights** |
 | Multi-agent timeline | No | No | No | **Yes** |
 | Cross-platform | Claude only | MCP only | Tool-specific | **Universal (MCP + npm)** |
 
@@ -195,10 +199,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` — 28 tools via MCP |
+| **MCP Local** | Claude Code, Cursor, Windsurf, Cline | `npx speclock serve` — 31 tools via MCP |
 | **npm File-Based** | Bolt.new, Aider, Rocket.new | `npx speclock setup` — AI reads SPECLOCK.md + uses CLI |
 
-## 28 MCP Tools
+## 31 MCP Tools
 
 ### Memory Management
 | Tool | Purpose |
@@ -260,6 +264,13 @@ Result:  NO CONFLICT (confidence: 7%)
 | `speclock_semantic_audit` | Semantic pre-commit: analyze code changes vs locks |
 | `speclock_override_history` | View lock override history for audit review |
 
+### Enterprise Platform (v3.5)
+| Tool | Purpose |
+|------|---------|
+| `speclock_policy_evaluate` | Evaluate policy-as-code rules against proposed actions |
+| `speclock_policy_manage` | CRUD for policy rules — list, add, remove, init, export |
+| `speclock_telemetry` | View opt-in telemetry summary and usage analytics |
+
 ## Auto-Guard: Locks That Actually Work
 
 When you add a lock, SpecLock **automatically finds and guards related files**:
@@ -334,6 +345,16 @@ speclock override <lockId> <reason>    # Override a lock with justification
 speclock overrides [--lock <id>]       # Show override history
 speclock audit-semantic                # Semantic pre-commit audit
 
+# Enterprise Platform (v3.5)
+speclock policy list                   # List policy rules
+speclock policy init                   # Initialize policy-as-code
+speclock policy add <name> --files <pattern> --actions <types> --enforce <level>
+speclock policy evaluate --files <f> --type <t>  # Evaluate against rules
+speclock policy export                 # Export policy as portable YAML
+speclock telemetry status              # View telemetry summary
+speclock sso status                    # Show SSO configuration
+speclock sso configure                 # Configure OAuth/OIDC SSO
+
 # Other
 speclock status                        # Show brain summary
 speclock serve [--project <path>]      # Start MCP server
@@ -419,7 +440,58 @@ SHA-256 hashed keys stored server-side. HTTP transport uses `Authorization: Bear
 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.
+**330+ tests passing** across 6 test suites. Full coverage for authentication, authorization, encryption, semantic detection, audit chain integrity, policy-as-code, telemetry, and SSO.
+
+## Enterprise Platform (v3.5)
+
+### Policy-as-Code DSL
+Declarative YAML-based policy rules for enterprise constraint enforcement:
+
+```yaml
+# .speclock/policy.yml
+rules:
+  - name: "HIPAA PHI Protection"
+    match:
+      files: ["**/patient/**", "**/medical/**"]
+      actions: [delete, modify, export]
+    enforce: block
+    severity: critical
+    notify: ["security@company.com", "slack:#compliance"]
+```
+
+- **File pattern matching**: Glob patterns (`**/patient/**`, `src/api/*.js`)
+- **Action-type filtering**: Block specific operations (delete, modify, create, export)
+- **Enforcement levels**: `block` (hard stop), `warn` (advisory), `log` (record only)
+- **Severity levels**: critical, high, medium, low
+- **Notification hooks**: Email, Slack, webhook channels
+- **Import/export**: Share policies between organizations
+
+### OAuth/OIDC SSO
+Enterprise single sign-on with corporate identity providers:
+
+- **Providers**: Okta, Azure AD, Auth0, any OIDC-compliant IdP
+- **PKCE flow**: Authorization Code with Proof Key (S256)
+- **Role mapping**: Map OIDC groups/roles to SpecLock roles (viewer/developer/architect/admin)
+- **Session management**: 8-hour TTL, token refresh, session listing/revocation
+- **MCP June 2025 spec**: OAuth compliance
+
+### Admin Dashboard
+Real-time web UI served from the HTTP server:
+
+- **Access**: `http://localhost:PORT/dashboard`
+- **Views**: Lock overview, violation timeline, session history, health score
+- **Metrics**: Enforcement mode, auth status, encryption status, audit chain integrity
+- **Zero dependencies**: Vanilla HTML/JS — no framework overhead
+- **Auto-refresh**: Updates every 30 seconds
+
+### Telemetry & Analytics
+Opt-in usage insights for product improvement:
+
+- **Disabled by default** — enable with `SPECLOCK_TELEMETRY=true`
+- **Tracks**: Tool usage counts, conflict detection rates, response times, feature adoption
+- **Never tracks**: Lock content, project names, any PII
+- **Local storage**: `.speclock/telemetry.json` with optional remote flush
+- **30-day rolling window**: Daily stats with trend analysis
 
 ---
 
@@ -431,7 +503,7 @@ Transparent encrypt-on-write / decrypt-on-read for `brain.json` and `events.log`
 └──────────────┬──────────────────┬────────────────────┘
                │                  │
      MCP Protocol          File-Based (npm)
-    (28 tool calls)      (reads SPECLOCK.md +
+    (31 tool calls)      (reads SPECLOCK.md +
                         .speclock/context/latest.md,
                          runs CLI commands)
                │                  │

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speclock",
-  "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.",
+  "version": "3.5.0",
+  "description": "AI constraint engine with Policy-as-Code DSL, OAuth/OIDC SSO, admin dashboard, telemetry, 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. 31 MCP tools + CLI. Enterprise platform.",
   "type": "module",
   "main": "src/mcp/server.js",
   "bin": {
@@ -41,7 +41,13 @@
     "aes-256",
     "api-key",
     "authentication",
-    "rbac"
+    "rbac",
+    "policy-as-code",
+    "sso",
+    "oauth",
+    "oidc",
+    "dashboard",
+    "telemetry"
   ],
   "author": "Sandeep Roy (https://github.com/sgroy10)",
   "license": "MIT",
@@ -64,6 +70,7 @@
   "files": [
     "bin/",
     "src/",
+    "src/dashboard/",
     "README.md",
     "SPECLOCK-INSTRUCTIONS.md",
     "LICENSE"

package/src/cli/index.js

@@ -43,6 +43,24 @@ import {
   listApiKeys,
 } from "../core/auth.js";
 import { isEncryptionEnabled } from "../core/crypto.js";
+import {
+  initPolicy,
+  addPolicyRule,
+  removePolicyRule,
+  listPolicyRules,
+  evaluatePolicy,
+  exportPolicy,
+  importPolicy,
+} from "../core/policy.js";
+import {
+  isTelemetryEnabled,
+  getTelemetrySummary,
+} from "../core/telemetry.js";
+import {
+  isSSOEnabled,
+  getSSOConfig,
+  saveSSOConfig,
+} from "../core/sso.js";
 
 // --- Argument parsing ---
 
@@ -98,7 +116,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v3.0.0 — AI Constraint Engine (Auth + RBAC + Encryption + Hard Enforcement)
+SpecLock v3.5.0 — AI Constraint Engine (Policy-as-Code + SSO + Dashboard + Telemetry + Auth + RBAC + Encryption)
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
@@ -146,6 +164,17 @@ Options:
 
 Templates: nextjs, react, express, supabase, stripe, security-hardened
 
+Policy-as-Code (v3.5):
+  policy list                     List all policy rules
+  policy init                     Initialize policy-as-code
+  policy add --name <name>        Add a policy rule (--files, --enforce, --severity)
+  policy remove <ruleId>          Remove a policy rule
+  policy evaluate <action>        Evaluate action against policy rules
+  policy export                   Export policy as YAML
+  telemetry [status]              Show telemetry status and analytics
+  sso status                      Show SSO configuration
+  sso configure --issuer <url>    Configure SSO (--client-id, --client-secret)
+
 Security (v3.0):
   auth status                     Show auth status and active keys
   auth create-key --role <role>   Create API key (viewer/developer/architect/admin)
@@ -210,6 +239,10 @@ 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"}`);
+  const policyRules = listPolicyRules(root);
+  console.log(`Policy rules: ${policyRules.active}/${policyRules.total}`);
+  console.log(`Telemetry: ${isTelemetryEnabled() ? "enabled" : "disabled"}`);
+  console.log(`SSO: ${isSSOEnabled(root) ? "configured" : "not configured"}`);
   console.log("");
 }
 
@@ -902,6 +935,146 @@ Tip: When starting a new chat, tell the AI:
     process.exit(1);
   }
 
+  // --- POLICY (v3.5) ---
+  if (cmd === "policy") {
+    const sub = args[0];
+    if (!sub || sub === "list") {
+      const result = listPolicyRules(root);
+      console.log(`\nPolicy Rules (${result.active}/${result.total} active):`);
+      console.log("=".repeat(50));
+      if (result.rules.length === 0) {
+        console.log("  No rules. Run 'speclock policy init' to create a policy.");
+      } else {
+        for (const r of result.rules) {
+          const status = r.active !== false ? "active" : "inactive";
+          console.log(`  ${r.id} — ${r.name} [${r.enforce}/${r.severity}] (${status})`);
+          console.log(`    Files: ${(r.match?.files || []).join(", ")}`);
+          console.log(`    Actions: ${(r.match?.actions || []).join(", ")}`);
+          console.log("");
+        }
+      }
+      return;
+    }
+    if (sub === "init") {
+      const result = initPolicy(root);
+      if (!result.success) { console.error(result.error); process.exit(1); }
+      console.log("Policy-as-code initialized. Edit .speclock/policy.yml to add rules.");
+      return;
+    }
+    if (sub === "add") {
+      const flags = parseFlags(args.slice(1));
+      const name = flags.name || flags._.join(" ");
+      if (!name) { console.error("Usage: speclock policy add --name <name> --files '**/*.js' --enforce block"); process.exit(1); }
+      const rule = {
+        name,
+        description: flags.description || "",
+        match: {
+          files: flags.files ? flags.files.split(",").map(s => s.trim()) : ["**/*"],
+          actions: flags.actions ? flags.actions.split(",").map(s => s.trim()) : ["modify", "delete"],
+        },
+        enforce: flags.enforce || "warn",
+        severity: flags.severity || "medium",
+        notify: flags.notify ? flags.notify.split(",").map(s => s.trim()) : [],
+      };
+      const result = addPolicyRule(root, rule);
+      if (!result.success) { console.error(result.error); process.exit(1); }
+      console.log(`Policy rule added: "${result.rule.name}" (${result.ruleId}) [${result.rule.enforce}]`);
+      return;
+    }
+    if (sub === "remove") {
+      const ruleId = args[1];
+      if (!ruleId) { console.error("Usage: speclock policy remove <ruleId>"); process.exit(1); }
+      const result = removePolicyRule(root, ruleId);
+      if (!result.success) { console.error(result.error); process.exit(1); }
+      console.log(`Policy rule removed: "${result.removed.name}"`);
+      return;
+    }
+    if (sub === "evaluate") {
+      const text = args.slice(1).join(" ");
+      if (!text) { console.error("Usage: speclock policy evaluate 'what you plan to do'"); process.exit(1); }
+      const result = evaluatePolicy(root, { description: text, text, type: "modify" });
+      if (result.passed) {
+        console.log(`Policy check passed. ${result.rulesChecked} rules evaluated.`);
+      } else {
+        console.log(`\nPolicy Violations (${result.violations.length}):`);
+        for (const v of result.violations) {
+          console.log(`  [${v.severity.toUpperCase()}] ${v.ruleName} (${v.enforce})`);
+          if (v.matchedFiles.length) console.log(`    Files: ${v.matchedFiles.join(", ")}`);
+        }
+        if (result.blocked) process.exit(1);
+      }
+      return;
+    }
+    if (sub === "export") {
+      const result = exportPolicy(root);
+      if (!result.success) { console.error(result.error); process.exit(1); }
+      console.log(result.yaml);
+      return;
+    }
+    console.error("Usage: speclock policy <list|init|add|remove|evaluate|export>");
+    process.exit(1);
+  }
+
+  // --- TELEMETRY (v3.5) ---
+  if (cmd === "telemetry") {
+    const sub = args[0];
+    if (sub === "status" || !sub) {
+      const enabled = isTelemetryEnabled();
+      console.log(`\nTelemetry: ${enabled ? "ENABLED" : "DISABLED"}`);
+      if (!enabled) {
+        console.log("Set SPECLOCK_TELEMETRY=true to enable anonymous usage analytics.");
+        return;
+      }
+      const summary = getTelemetrySummary(root);
+      console.log(`Total calls: ${summary.totalCalls}`);
+      console.log(`Avg response: ${summary.avgResponseMs}ms`);
+      console.log(`Sessions: ${summary.sessions.total}`);
+      console.log(`Conflicts: ${summary.conflicts.total} (blocked: ${summary.conflicts.blocked})`);
+      if (summary.topTools.length > 0) {
+        console.log(`\nTop tools:`);
+        for (const t of summary.topTools.slice(0, 5)) {
+          console.log(`  ${t.name}: ${t.count} calls`);
+        }
+      }
+      return;
+    }
+    console.error("Usage: speclock telemetry [status]");
+    process.exit(1);
+  }
+
+  // --- SSO (v3.5) ---
+  if (cmd === "sso") {
+    const sub = args[0];
+    if (sub === "status" || !sub) {
+      const enabled = isSSOEnabled(root);
+      const config = getSSOConfig(root);
+      console.log(`\nSSO: ${enabled ? "CONFIGURED" : "NOT CONFIGURED"}`);
+      if (enabled) {
+        console.log(`Issuer: ${config.issuer}`);
+        console.log(`Client ID: ${config.clientId}`);
+        console.log(`Redirect: ${config.redirectUri}`);
+        console.log(`Default role: ${config.defaultRole}`);
+      } else {
+        console.log("Set SPECLOCK_SSO_ISSUER and SPECLOCK_SSO_CLIENT_ID to enable SSO.");
+      }
+      return;
+    }
+    if (sub === "configure") {
+      const flags = parseFlags(args.slice(1));
+      const config = getSSOConfig(root);
+      if (flags.issuer) config.issuer = flags.issuer;
+      if (flags["client-id"]) config.clientId = flags["client-id"];
+      if (flags["client-secret"]) config.clientSecret = flags["client-secret"];
+      if (flags["redirect-uri"]) config.redirectUri = flags["redirect-uri"];
+      if (flags["default-role"]) config.defaultRole = flags["default-role"];
+      saveSSOConfig(root, config);
+      console.log("SSO configuration saved.");
+      return;
+    }
+    console.error("Usage: speclock sso <status|configure> [--issuer URL --client-id ID]");
+    process.exit(1);
+  }
+
   // --- ENCRYPT STATUS (v3.0) ---
   if (cmd === "encrypt") {
     const sub = args[0];

package/src/core/compliance.js

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

package/src/core/engine.js

@@ -556,3 +556,41 @@ export {
   decrypt,
   clearKeyCache,
 } from "./crypto.js";
+
+// --- Policy-as-Code (v3.5) ---
+export {
+  loadPolicy,
+  savePolicy,
+  initPolicy,
+  addPolicyRule,
+  removePolicyRule,
+  listPolicyRules,
+  evaluatePolicy,
+  exportPolicy,
+  importPolicy,
+  generateNotifications,
+} from "./policy.js";
+
+// --- Telemetry & Analytics (v3.5) ---
+export {
+  isTelemetryEnabled,
+  trackToolUsage,
+  trackConflict,
+  trackFeature,
+  trackSession,
+  getTelemetrySummary,
+  flushToRemote,
+  resetTelemetry,
+} from "./telemetry.js";
+
+// --- OAuth/OIDC SSO (v3.5) ---
+export {
+  isSSOEnabled,
+  getSSOConfig,
+  saveSSOConfig,
+  getAuthorizationUrl,
+  handleCallback,
+  validateSession,
+  revokeSession,
+  listSessions,
+} from "./sso.js";