speclock 2.5.0 → 3.5.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.5.0";
+const VERSION = "3.5.0";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [

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/engine.js

@@ -532,3 +532,65 @@ export function applyTemplate(root, templateName) {
 export { verifyAuditChain } from "./audit.js";
 export { exportCompliance } from "./compliance.js";
 export { checkFeature, checkLimits, getLicenseInfo } from "./license.js";
+
+// --- Authentication & RBAC (v3.0) ---
+export {
+  isAuthEnabled,
+  enableAuth,
+  disableAuth,
+  createApiKey,
+  validateApiKey,
+  checkPermission,
+  rotateApiKey,
+  revokeApiKey,
+  listApiKeys,
+  ROLES,
+  TOOL_PERMISSIONS,
+} from "./auth.js";
+
+// --- Encrypted Storage (v3.0) ---
+export {
+  isEncryptionEnabled,
+  isEncrypted,
+  encrypt,
+  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";