@devran-ai/kit 4.1.0

package/lib/plugin-verifier.js

@@ -0,0 +1,197 @@
+/**
+ * Devran AI Kit — Plugin Signature Verification
+ *
+ * Generates and validates SHA-256 checksums for plugin integrity.
+ * Prevents supply chain attacks by verifying plugin contents
+ * have not been tampered with after installation.
+ *
+ * @module lib/plugin-verifier
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { AGENT_DIR, ENGINE_DIR, PLUGINS_DIR } = require('./constants');
+
+/**
+ * @typedef {object} PluginChecksum
+ * @property {string} pluginName - Plugin name
+ * @property {string} checksum - SHA-256 checksum of concatenated file contents
+ * @property {string[]} files - Files included in checksum
+ * @property {string} generatedAt - ISO timestamp
+ */
+
+/**
+ * Collects all files in a directory recursively.
+ *
+ * @param {string} dirPath - Directory to scan
+ * @returns {string[]} Sorted list of relative file paths
+ */
+function collectPluginFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    return [];
+  }
+
+  const files = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory() && entry.name !== 'node_modules' && entry.name !== '.git') {
+      files.push(...collectPluginFiles(fullPath));
+    } else if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files.sort();
+}
+
+/**
+ * Generates a SHA-256 checksum for a plugin directory.
+ *
+ * @param {string} pluginDir - Path to plugin directory
+ * @returns {PluginChecksum}
+ */
+function generateChecksum(pluginDir) {
+  const files = collectPluginFiles(pluginDir);
+  const hash = crypto.createHash('sha256');
+  const relativeFiles = [];
+
+  for (const file of files) {
+    const relativePath = path.relative(pluginDir, file).replace(/\\/g, '/');
+    relativeFiles.push(relativePath);
+
+    // Hash both the file path and contents for integrity
+    hash.update(relativePath);
+    hash.update(fs.readFileSync(file));
+  }
+
+  const manifestPath = path.join(pluginDir, 'plugin.json');
+  let pluginName = 'unknown';
+  if (fs.existsSync(manifestPath)) {
+    try {
+      pluginName = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')).name || 'unknown';
+    } catch {
+      // Use default
+    }
+  }
+
+  return {
+    pluginName,
+    checksum: hash.digest('hex'),
+    files: relativeFiles,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Verifies a plugin's current state matches its stored checksum.
+ *
+ * @param {string} pluginDir - Path to plugin directory
+ * @param {string} expectedChecksum - Expected SHA-256 checksum
+ * @returns {{ valid: boolean, currentChecksum: string, expectedChecksum: string }}
+ */
+function verifyChecksum(pluginDir, expectedChecksum) {
+  const current = generateChecksum(pluginDir);
+
+  return {
+    valid: current.checksum === expectedChecksum,
+    currentChecksum: current.checksum,
+    expectedChecksum,
+  };
+}
+
+/**
+ * Stores a checksum in the plugin's registry entry.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} pluginName - Plugin name
+ * @param {string} checksum - SHA-256 checksum to store
+ * @returns {void}
+ */
+function storeChecksum(projectRoot, pluginName, checksum) {
+  const checksumDir = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'plugin-checksums');
+
+  if (!fs.existsSync(checksumDir)) {
+    fs.mkdirSync(checksumDir, { recursive: true });
+  }
+
+  const checksumPath = path.join(checksumDir, `${pluginName}.sha256`);
+  fs.writeFileSync(checksumPath, checksum, 'utf-8');
+}
+
+/**
+ * Retrieves a stored checksum for a plugin.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} pluginName - Plugin name
+ * @returns {string | null}
+ */
+function getStoredChecksum(projectRoot, pluginName) {
+  const checksumPath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'plugin-checksums', `${pluginName}.sha256`);
+
+  if (!fs.existsSync(checksumPath)) {
+    return null;
+  }
+
+  return fs.readFileSync(checksumPath, 'utf-8').trim();
+}
+
+/**
+ * Verifies all installed plugins against their stored checksums.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {{ total: number, valid: number, invalid: string[], unverified: string[] }}
+ */
+function verifyAllPlugins(projectRoot) {
+  const pluginsDir = path.join(projectRoot, AGENT_DIR, PLUGINS_DIR);
+
+  if (!fs.existsSync(pluginsDir)) {
+    return { total: 0, valid: 0, invalid: [], unverified: [] };
+  }
+
+  const entries = fs.readdirSync(pluginsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory());
+
+  const invalid = [];
+  const unverified = [];
+  let valid = 0;
+
+  for (const entry of entries) {
+    const pluginDir = path.join(pluginsDir, entry.name);
+    const storedChecksum = getStoredChecksum(projectRoot, entry.name);
+
+    if (!storedChecksum) {
+      unverified.push(entry.name);
+      continue;
+    }
+
+    const result = verifyChecksum(pluginDir, storedChecksum);
+    if (result.valid) {
+      valid += 1;
+    } else {
+      invalid.push(entry.name);
+    }
+  }
+
+  return {
+    total: entries.length,
+    valid,
+    invalid,
+    unverified,
+  };
+}
+
+module.exports = {
+  generateChecksum,
+  verifyChecksum,
+  storeChecksum,
+  getStoredChecksum,
+  verifyAllPlugins,
+};

package/lib/rate-limiter.js

@@ -0,0 +1,113 @@
+/**
+ * Devran AI Kit — Rate Limiter
+ *
+ * Token bucket rate limiter for protecting external operations
+ * (marketplace git clones, API calls) from abuse and resource exhaustion.
+ *
+ * @module lib/rate-limiter
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+/**
+ * @typedef {object} RateLimiterOptions
+ * @property {number} [maxTokens=5] - Maximum tokens (burst capacity)
+ * @property {number} [refillRateMs=60000] - Time to refill one token (ms)
+ */
+
+/**
+ * @typedef {object} RateLimiterState
+ * @property {string} name - Limiter name
+ * @property {number} tokens - Current available tokens
+ * @property {number} maxTokens - Maximum capacity
+ * @property {number} refillRateMs - Refill interval per token
+ * @property {number} lastRefillTime - Last refill timestamp
+ * @property {number} totalAllowed - Lifetime allowed count
+ * @property {number} totalRejected - Lifetime rejected count
+ */
+
+/**
+ * Creates a new rate limiter instance.
+ *
+ * @param {string} name - Rate limiter name for identification
+ * @param {RateLimiterOptions} [options] - Configuration
+ * @returns {{ tryAcquire: Function, getState: Function, reset: Function }}
+ */
+function createRateLimiter(name, options = {}) {
+  const maxTokens = options.maxTokens || 5;
+  const refillRateMs = options.refillRateMs || 60000;
+
+  /** @type {RateLimiterState} */
+  const state = {
+    name,
+    tokens: maxTokens,
+    maxTokens,
+    refillRateMs,
+    lastRefillTime: Date.now(),
+    totalAllowed: 0,
+    totalRejected: 0,
+  };
+
+  /**
+   * Refills tokens based on elapsed time since last refill.
+   *
+   * @returns {void}
+   */
+  function refill() {
+    const now = Date.now();
+    const elapsed = now - state.lastRefillTime;
+    const tokensToAdd = Math.floor(elapsed / refillRateMs);
+
+    if (tokensToAdd > 0) {
+      state.tokens = Math.min(maxTokens, state.tokens + tokensToAdd);
+      state.lastRefillTime = now;
+    }
+  }
+
+  /**
+   * Attempts to acquire a token for an operation.
+   *
+   * @returns {{ allowed: boolean, retryAfterMs?: number }}
+   */
+  function tryAcquire() {
+    refill();
+
+    if (state.tokens > 0) {
+      state.tokens -= 1;
+      state.totalAllowed += 1;
+      return { allowed: true };
+    }
+
+    state.totalRejected += 1;
+    const timeSinceLastRefill = Date.now() - state.lastRefillTime;
+    const retryAfterMs = Math.max(0, refillRateMs - timeSinceLastRefill);
+
+    return { allowed: false, retryAfterMs };
+  }
+
+  /**
+   * Returns a snapshot of the rate limiter state.
+   *
+   * @returns {RateLimiterState}
+   */
+  function getState() {
+    refill();
+    return { ...state };
+  }
+
+  /**
+   * Resets the rate limiter to full capacity.
+   *
+   * @returns {void}
+   */
+  function reset() {
+    state.tokens = maxTokens;
+    state.lastRefillTime = Date.now();
+  }
+
+  return { tryAcquire, getState, reset };
+}
+
+module.exports = { createRateLimiter };

package/lib/security-scanner.js

@@ -0,0 +1,312 @@
+/**
+ * Devran AI Kit — Enhanced Security Scanner
+ *
+ * Runtime injection detection, secret scanning, and anomaly alerting
+ * for agent and skill files.
+ *
+ * @module lib/security-scanner
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { AGENT_DIR } = require('./constants');
+
+/** Paths that are known-safe and should be excluded from injection/secret scanning */
+const ALLOWLISTED_DIRS = ['decisions', 'engine'];
+
+/** Prompt injection patterns */
+const INJECTION_PATTERNS = [
+  { pattern: /ignore\s+(all\s+)?previous\s+instructions/gi, name: 'ignore-previous', severity: 'critical' },
+  { pattern: /system\s+override/gi, name: 'system-override', severity: 'critical' },
+  { pattern: /you\s+are\s+now\s+a/gi, name: 'role-hijacking', severity: 'critical' },
+  { pattern: /act\s+as\s+(if\s+you\s+are|a\s+different)/gi, name: 'persona-override', severity: 'high' },
+  { pattern: /forget\s+(everything|your|all)/gi, name: 'memory-wipe', severity: 'critical' },
+  { pattern: /disregard\s+(all|your|the)/gi, name: 'disregard-instructions', severity: 'high' },
+  { pattern: /\bDAN\b.*\bjailbreak\b/gi, name: 'jailbreak-reference', severity: 'critical' },
+  { pattern: /bypass\s+(safety|security|filter|restriction)/gi, name: 'bypass-safety', severity: 'critical' },
+  { pattern: /pretend\s+(you|that)\s+(are|have)\s+no\s+(restrictions|rules|limits)/gi, name: 'pretend-no-rules', severity: 'high' },
+];
+
+/** Secret patterns */
+const SECRET_PATTERNS = [
+  { pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"][A-Za-z0-9_\-]{20,}['"]/gi, name: 'api-key', severity: 'critical' },
+  { pattern: /ghp_[A-Za-z0-9_]{36,}/g, name: 'github-pat', severity: 'critical' },
+  { pattern: /gho_[A-Za-z0-9_]{36,}/g, name: 'github-oauth', severity: 'critical' },
+  { pattern: /sk-[A-Za-z0-9]{32,}/g, name: 'openai-key', severity: 'critical' },
+  { pattern: /AKIA[A-Z0-9]{16}/g, name: 'aws-access-key', severity: 'critical' },
+  { pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/g, name: 'private-key', severity: 'critical' },
+];
+
+/** Maximum expected file size for agent/skill files (100KB) */
+const MAX_EXPECTED_SIZE = 100 * 1024;
+/** Minimum expected file size for legitimate files */
+const MIN_EXPECTED_SIZE = 50;
+
+/**
+ * @typedef {object} SecurityFinding
+ * @property {string} type - Finding type (injection, secret, anomaly)
+ * @property {string} name - Pattern name
+ * @property {'critical' | 'high' | 'medium' | 'low'} severity - Finding severity
+ * @property {string} file - File where finding was detected
+ * @property {number} [line] - Line number
+ * @property {string} detail - Description of the finding
+ */
+
+/**
+ * @typedef {object} SecurityReport
+ * @property {number} filesScanned - Total files scanned
+ * @property {number} criticalCount - Critical findings count
+ * @property {number} highCount - High findings count
+ * @property {number} mediumCount - Medium findings count
+ * @property {number} lowCount - Low findings count
+ * @property {SecurityFinding[]} findings - All findings
+ * @property {boolean} clean - Whether no critical/high findings exist
+ */
+
+/**
+ * Recursively collects scannable files from a directory.
+ *
+ * @param {string} dirPath - Directory to scan
+ * @param {string} projectRoot - Project root for relative paths
+ * @returns {string[]}
+ */
+function collectFiles(dirPath, projectRoot) {
+  /** @type {string[]} */
+  const files = [];
+
+  if (!fs.existsSync(dirPath)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory() && entry.name !== 'node_modules' && entry.name !== '.git') {
+      files.push(...collectFiles(fullPath, projectRoot));
+    } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.json') || entry.name.endsWith('.js'))) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Scans for prompt injection patterns.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {SecurityFinding[]}
+ */
+function scanForInjection(projectRoot) {
+  const agentDir = path.join(projectRoot, AGENT_DIR);
+  const files = collectFiles(agentDir, projectRoot);
+  /** @type {SecurityFinding[]} */
+  const findings = [];
+
+  for (const file of files) {
+    const relativePath = path.relative(path.join(projectRoot, AGENT_DIR), file);
+
+    // Skip allowlisted directories (governance docs, engine configs)
+    if (ALLOWLISTED_DIRS.some((dir) => relativePath.startsWith(dir + path.sep) || relativePath.startsWith(dir + '/'))) {
+      continue;
+    }
+    const content = fs.readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
+
+      for (const { pattern, name, severity } of INJECTION_PATTERNS) {
+        // Reset regex lastIndex for global patterns
+        pattern.lastIndex = 0;
+        if (pattern.test(line)) {
+          findings.push({
+            type: 'injection',
+            name,
+            severity,
+            file: path.relative(projectRoot, file),
+            line: lineIndex + 1,
+            detail: `Prompt injection pattern "${name}" detected`,
+          });
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Scans for hardcoded secrets.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {SecurityFinding[]}
+ */
+function scanForSecrets(projectRoot) {
+  const agentDir = path.join(projectRoot, AGENT_DIR);
+  const files = collectFiles(agentDir, projectRoot);
+  /** @type {SecurityFinding[]} */
+  const findings = [];
+
+  for (const file of files) {
+    const relativePath = path.relative(path.join(projectRoot, AGENT_DIR), file);
+
+    // Skip allowlisted directories and skill documentation
+    if (ALLOWLISTED_DIRS.some((dir) => relativePath.startsWith(dir + path.sep) || relativePath.startsWith(dir + '/'))) {
+      continue;
+    }
+
+    const content = fs.readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
+
+      for (const { pattern, name, severity } of SECRET_PATTERNS) {
+        pattern.lastIndex = 0;
+        if (pattern.test(line)) {
+          findings.push({
+            type: 'secret',
+            name,
+            severity,
+            file: path.relative(projectRoot, file),
+            line: lineIndex + 1,
+            detail: `Potential ${name} found — never commit secrets`,
+          });
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Scans for file anomalies (unusual sizes, unexpected file types).
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {SecurityFinding[]}
+ */
+function scanForAnomalies(projectRoot) {
+  const agentDir = path.join(projectRoot, AGENT_DIR);
+  /** @type {SecurityFinding[]} */
+  const findings = [];
+
+  if (!fs.existsSync(agentDir)) {
+    return findings;
+  }
+
+  const allFiles = collectAllFiles(agentDir);
+
+  for (const file of allFiles) {
+    const stats = fs.statSync(file);
+    const relativePath = path.relative(projectRoot, file);
+    const ext = path.extname(file).toLowerCase();
+
+    // Check for binary files in agent directories
+    const textExtensions = ['.md', '.json', '.js', '.ts', '.yaml', '.yml', '.txt', '.csv', '.toml'];
+    if (!textExtensions.includes(ext) && ext !== '') {
+      findings.push({
+        type: 'anomaly',
+        name: 'unexpected-file-type',
+        severity: 'medium',
+        file: relativePath,
+        detail: `Unexpected file type "${ext}" in agent directory`,
+      });
+    }
+
+    // Check for oversized files
+    if (stats.size > MAX_EXPECTED_SIZE) {
+      findings.push({
+        type: 'anomaly',
+        name: 'oversized-file',
+        severity: 'high',
+        file: relativePath,
+        detail: `File size ${Math.round(stats.size / 1024)}KB exceeds ${MAX_EXPECTED_SIZE / 1024}KB limit`,
+      });
+    }
+
+    // Check for suspiciously small files (possible stubs)
+    if (stats.size < MIN_EXPECTED_SIZE && stats.size > 0 && textExtensions.includes(ext)) {
+      findings.push({
+        type: 'anomaly',
+        name: 'tiny-file',
+        severity: 'low',
+        file: relativePath,
+        detail: `File is only ${stats.size} bytes — possible incomplete stub`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Collects ALL files (not just text) from a directory.
+ *
+ * @param {string} dirPath - Directory to scan
+ * @returns {string[]}
+ */
+function collectAllFiles(dirPath) {
+  /** @type {string[]} */
+  const files = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    // Security: skip symlinks to prevent path traversal
+    const stat = fs.lstatSync(fullPath);
+    if (stat.isSymbolicLink()) {
+      continue;
+    }
+
+    if (entry.isDirectory() && entry.name !== 'node_modules' && entry.name !== '.git') {
+      files.push(...collectAllFiles(fullPath));
+    } else if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Generates a comprehensive security report.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {SecurityReport}
+ */
+function getSecurityReport(projectRoot) {
+  const injectionFindings = scanForInjection(projectRoot);
+  const secretFindings = scanForSecrets(projectRoot);
+  const anomalyFindings = scanForAnomalies(projectRoot);
+
+  const allFindings = [...injectionFindings, ...secretFindings, ...anomalyFindings];
+  const agentDir = path.join(projectRoot, AGENT_DIR);
+  const filesScanned = fs.existsSync(agentDir) ? collectAllFiles(agentDir).length : 0;
+
+  return {
+    filesScanned,
+    criticalCount: allFindings.filter((f) => f.severity === 'critical').length,
+    highCount: allFindings.filter((f) => f.severity === 'high').length,
+    mediumCount: allFindings.filter((f) => f.severity === 'medium').length,
+    lowCount: allFindings.filter((f) => f.severity === 'low').length,
+    findings: allFindings,
+    clean: allFindings.filter((f) => f.severity === 'critical' || f.severity === 'high').length === 0,
+  };
+}
+
+module.exports = {
+  scanForInjection,
+  scanForSecrets,
+  scanForAnomalies,
+  getSecurityReport,
+};