antigravity-ai-kit 3.1.1 → 3.2.0

package/lib/plugin-system.js

@@ -15,11 +15,11 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
-const PLUGINS_DIR = 'plugins';
+const { AGENT_DIR, ENGINE_DIR, PLUGINS_DIR, HOOKS_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const { createLogger } = require('./logger');
+const log = createLogger('plugin-system');
 const PLUGINS_REGISTRY = 'plugins-registry.json';
-const HOOKS_DIR = 'hooks';
 const HOOKS_FILE = 'hooks.json';
 
 /** Required fields in plugin.json */
@@ -97,15 +97,7 @@ function loadRegistry(projectRoot) {
  */
 function writeRegistry(projectRoot, registry) {
   const registryPath = resolveRegistryPath(projectRoot);
-  const tempPath = `${registryPath}.tmp`;
-  const dir = path.dirname(registryPath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  fs.writeFileSync(tempPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, registryPath);
+  writeJsonAtomic(registryPath, registry);
 }
 
 /**
@@ -168,7 +160,7 @@ function validatePlugin(pluginPath) {
   }
 
   // Validate hook event names
-  const validEvents = ['session-start', 'session-end', 'pre-commit', 'secret-detection', 'phase-transition', 'sprint-checkpoint'];
+  const validEvents = ['session-start', 'session-end', 'pre-commit', 'secret-detection', 'phase-transition', 'sprint-checkpoint', 'plan-complete'];
   for (const hook of (manifest.hooks || [])) {
     if (!hook.event || !validEvents.includes(hook.event)) {
       errors.push(`Invalid hook event: ${hook.event || 'undefined'}. Valid: ${validEvents.join(', ')}`);
@@ -485,9 +477,7 @@ function mergeHooks(pluginHooks, pluginName, projectRoot) {
     }
   }
 
-  const tempPath = `${hooksPath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(hooksConfig, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, hooksPath);
+  writeJsonAtomic(hooksPath, hooksConfig);
 }
 
 /**
@@ -514,9 +504,31 @@ function unmergeHooks(pluginName, projectRoot) {
   // Remove hooks with no actions remaining
   hooksConfig.hooks = hooksConfig.hooks.filter((h) => h.actions.length > 0);
 
-  const tempPath = `${hooksPath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(hooksConfig, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, hooksPath);
+  writeJsonAtomic(hooksPath, hooksConfig);
+}
+
+/**
+ * Recursively sanitizes a value by stripping prototype-polluting keys
+ * at all nesting levels. Returns a clean copy without mutating the input.
+ *
+ * @param {*} val - Value to sanitize
+ * @returns {*} Sanitized copy
+ */
+function sanitizeValue(val) {
+  if (val === null || typeof val !== 'object') {
+    return val;
+  }
+  if (Array.isArray(val)) {
+    return val.map(sanitizeValue);
+  }
+  const clean = {};
+  for (const [k, v] of Object.entries(val)) {
+    if (k === '__proto__' || k === 'constructor' || k === 'prototype') {
+      continue;
+    }
+    clean[k] = sanitizeValue(v);
+  }
+  return clean;
 }
 
 /**
@@ -529,28 +541,40 @@ function unmergeHooks(pluginName, projectRoot) {
  */
 function applyEngineConfigs(configs, pluginName, projectRoot) {
   for (const [configFile, patches] of Object.entries(configs)) {
+    // Reject path traversal in config file names
+    if (configFile.includes('/') || configFile.includes('\\') || configFile.includes('..')) {
+      continue;
+    }
+
     const configPath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, configFile);
 
     if (!fs.existsSync(configPath)) {
       continue;
     }
 
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    let config;
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch {
+      continue;
+    }
 
-    // Shallow merge patches
+    // Deep merge patches with recursive prototype pollution guard (H-5)
     for (const [key, value] of Object.entries(patches)) {
-      config[key] = value;
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+        continue;
+      }
+      config[key] = sanitizeValue(value);
     }
 
-    // Track which plugin patched this config
-    if (!config._pluginPatches) {
-      config._pluginPatches = {};
-    }
-    config._pluginPatches[pluginName] = Object.keys(patches);
+    // Track which plugin patched this config (immutable construction)
+    const pluginPatches = {
+      ...(config._pluginPatches || {}),
+      [pluginName]: Object.keys(patches),
+    };
+    config._pluginPatches = pluginPatches;
 
-    const tempPath = `${configPath}.tmp`;
-    fs.writeFileSync(tempPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-    fs.renameSync(tempPath, configPath);
+    writeJsonAtomic(configPath, config);
   }
 }
 

package/lib/plugin-verifier.js

@@ -0,0 +1,197 @@
+/**
+ * Antigravity 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 @@
+/**
+ * Antigravity 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

@@ -14,7 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
+const { AGENT_DIR } = require('./constants');
 
 /** Paths that are known-safe and should be excluded from injection/secret scanning */
 const ALLOWLISTED_DIRS = ['decisions', 'engine'];
@@ -163,9 +163,6 @@ function scanForSecrets(projectRoot) {
       continue;
     }
 
-    // Skip files in skills that mention password in example/testing contexts
-    const isSkillDoc = relativePath.includes('skills' + path.sep) || relativePath.includes('skills/');
-
     const content = fs.readFileSync(file, 'utf-8');
     const lines = content.split('\n');
 

package/lib/self-healing.js

@@ -14,15 +14,37 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { writeJsonAtomic } = require('./io');
+const { createLogger } = require('./logger');
+const log = createLogger('self-healing');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
 const HEALING_LOG_FILE = 'healing-log.json';
-const LAST_CI_OUTPUT_FILE = 'last-ci-output.txt';
 
 /** Maximum healing log entries before pruning */
 const MAX_LOG_ENTRIES = 100;
 
+/**
+ * Sanitizes a module path into a valid JavaScript variable name.
+ * Handles scoped packages (@scope/name), paths with slashes,
+ * and ensures the result starts with a letter.
+ *
+ * @param {string} modulePath - Raw module name or path
+ * @returns {string} Valid JS variable name
+ */
+function sanitizeVariableName(modulePath) {
+  // Extract the last segment (handle scoped packages and paths)
+  const segments = modulePath.replace('@', '').split(/[/\\]/);
+  const baseName = segments[segments.length - 1] || 'module';
+
+  // Convert to camelCase: strip non-alphanumeric, capitalize after separators
+  const sanitized = baseName
+    .replace(/[^a-zA-Z0-9]+(.)?/g, (_, chr) => (chr ? chr.toUpperCase() : ''))
+    .replace(/^[^a-zA-Z]/, '');
+
+  return sanitized || 'unknownModule';
+}
+
 /**
  * @typedef {object} FailureDetection
  * @property {string} type - Failure type: 'test' | 'build' | 'dependency' | 'lint'
@@ -89,20 +111,13 @@ function loadHealingLog(projectRoot) {
  */
 function writeHealingLog(projectRoot, data) {
   const filePath = resolveHealingLogPath(projectRoot);
-  const dir = path.dirname(filePath);
 
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
+  // Prune to last MAX_LOG_ENTRIES (immutable)
+  const prunedData = data.entries.length > MAX_LOG_ENTRIES
+    ? { ...data, entries: data.entries.slice(-MAX_LOG_ENTRIES) }
+    : data;
 
-  // Prune to last MAX_LOG_ENTRIES
-  if (data.entries.length > MAX_LOG_ENTRIES) {
-    data.entries = data.entries.slice(-MAX_LOG_ENTRIES);
-  }
-
-  const tempPath = `${filePath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, filePath);
+  writeJsonAtomic(filePath, prunedData);
 }
 
 // ═══════════════════════════════════════════════════
@@ -292,7 +307,9 @@ function generateFixPatch(failure, diagnosis) {
   // Missing import → suggest adding import
   if (diagnosis.category === 'import') {
     const moduleMatch = failure.message.match(/(?:Cannot find module|Module not found)[:\s]*'?([^'"\s]+)/i);
-    const moduleName = moduleMatch ? moduleMatch[1] : 'unknown-module';
+    const rawModuleName = moduleMatch ? moduleMatch[1] : 'unknown-module';
+    // Sanitize module name to prevent injection via crafted CI output (M-11)
+    const safeModuleName = rawModuleName.replace(/[^a-zA-Z0-9@/_.-]/g, '');
 
     return {
       patchId,
@@ -300,7 +317,7 @@ function generateFixPatch(failure, diagnosis) {
       type: 'insert',
       line: 1,
       original: '',
-      replacement: `const ${moduleName.replace(/[^a-zA-Z]/g, '')} = require('${moduleName}');`,
+      replacement: `const ${sanitizeVariableName(safeModuleName)} = require('${safeModuleName}');`,
       confidence: 'medium',
     };
   }
@@ -361,9 +378,26 @@ function applyFixWithConfirmation(projectRoot, patch, options = {}) {
   if (!dryRun && patch.file !== 'unknown') {
     const targetPath = path.join(projectRoot, patch.file);
 
+    // Validate target stays within project root (prevent path traversal via crafted CI logs)
+    const resolvedTarget = path.resolve(targetPath);
+    const resolvedRoot = path.resolve(projectRoot);
+    if (!resolvedTarget.startsWith(resolvedRoot + path.sep) && resolvedTarget !== resolvedRoot) {
+      logEntry.applied = false;
+      // Load healing log and record the blocked attempt (H-6: fixed variable shadowing)
+      const healingLog = loadHealingLog(projectRoot);
+      writeHealingLog(projectRoot, { ...healingLog, entries: [...healingLog.entries, logEntry] });
+      return { applied: false, preview, patchId: patch.patchId };
+    }
+
     if (fs.existsSync(targetPath)) {
       try {
         const content = fs.readFileSync(targetPath, 'utf-8');
+
+        // Create backup before applying patch
+        const backupPath = `${targetPath}.bak`;
+        fs.writeFileSync(backupPath, content, 'utf-8');
+        logEntry.rollbackData.backupPath = backupPath;
+
         const lines = content.split('\n');
 
         if (patch.type === 'insert' && patch.line !== null) {
@@ -392,10 +426,9 @@ function applyFixWithConfirmation(projectRoot, patch, options = {}) {
     }
   }
 
-  // Log the action
-  const log = loadHealingLog(projectRoot);
-  log.entries.push(logEntry);
-  writeHealingLog(projectRoot, log);
+  // Log the action (using distinct variable name to avoid shadowing logger)
+  const healingLog = loadHealingLog(projectRoot);
+  writeHealingLog(projectRoot, { ...healingLog, entries: [...healingLog.entries, logEntry] });
 
   return {
     applied: logEntry.applied,
@@ -414,12 +447,13 @@ function getHealingReport(projectRoot) {
   const log = loadHealingLog(projectRoot);
   const entries = log.entries || [];
 
-  const applied = entries.filter((e) => e.applied).length;
-  const dryRuns = entries.filter((e) => e.dryRun && !e.applied).length;
+  const appliedEntries = entries.filter((e) => !e.dryRun);
+  const applied = appliedEntries.filter((e) => e.applied).length;
+  const dryRuns = entries.filter((e) => e.dryRun).length;
 
   return {
     totalHeals: entries.length,
-    successRate: entries.length > 0 ? Math.round((applied / entries.length) * 100) : 0,
+    successRate: appliedEntries.length > 0 ? Math.round((applied / appliedEntries.length) * 100) : 0,
     recentEntries: entries.slice(-5),
     pendingPatches: dryRuns,
   };