devassist-agent 1.0.0

package/src/modules/runtime/schema-gatekeeper.js

@@ -0,0 +1,664 @@
+/**
+ * SchemaGatekeeper (Runtime) - Protocol and data validation at runtime
+ *
+ * Design from SyntaxGatekeeper_架构分析报告.md:
+ *   - 4-layer defense: syntax, schema, semantic, security
+ *   - 33 rules (adapted from SyntaxGatekeeper for runtime use)
+ *   - Validates: tool input/output, API responses, config data
+ *
+ * This is the RUNTIME version that runs inside the server, validating
+ * data as it flows through the system. The dev-time version (in dev-time/
+ * folder) checks source code. This one checks live data.
+ *
+ * Key principle: "Never trust input, always validate."
+ * Directly defends against failure #5 (ID/Class confusion — wrong data shape)
+ * and failure #6 (no defensive programming — unchecked null/undefined).
+ */
+
+const { bus } = require('../../core/event-bus');
+const { Logger } = require('../../core/logger');
+
+const log = new Logger('SchemaGatekeeper');
+
+const SEVERITY = {
+  PASS:    'pass',
+  WARN:    'warn',
+  REJECT:  'reject',
+};
+
+const LAYERS = {
+  SYNTAX:    'syntax',     // Layer 1: Basic structural validation
+  SCHEMA:    'schema',     // Layer 2: Schema conformance
+  SEMANTIC:  'semantic',   // Layer 3: Business logic validation
+  SECURITY:  'security',   // Layer 4: Security checks
+};
+
+// ============ Validation Rules ============
+
+/**
+ * Rule registry. Each rule has:
+ *   { id, layer, severity, check(data, schema, ctx) -> { passed, message, details } }
+ */
+const RULES = [];
+
+/**
+ * Register a validation rule.
+ */
+function registerRule(rule) {
+  if (!rule.id || !rule.layer || typeof rule.check !== 'function') {
+    throw new Error('Rule must have id, layer, and check function');
+  }
+  RULES.push(rule);
+}
+
+// --- Layer 1: Syntax Rules ---
+
+registerRule({
+  id: 'rt-syntax-001',
+  layer: LAYERS.SYNTAX,
+  severity: SEVERITY.REJECT,
+  description: 'Data must be a valid JSON-serializable object',
+  check(data) {
+    try {
+      JSON.stringify(data);
+      return { passed: true };
+    } catch (e) {
+      return { passed: false, message: `Data is not JSON-serializable: ${e.message}` };
+    }
+  },
+});
+
+registerRule({
+  id: 'rt-syntax-002',
+  layer: LAYERS.SYNTAX,
+  severity: SEVERITY.REJECT,
+  description: 'No circular references in data',
+  check(data) {
+    const seen = new WeakSet();
+    function detect(obj) {
+      if (obj === null || typeof obj !== 'object') return false;
+      if (seen.has(obj)) return true;
+      seen.add(obj);
+      for (const key of Object.keys(obj)) {
+        if (detect(obj[key])) return true;
+      }
+      return false;
+    }
+    if (detect(data)) {
+      return { passed: false, message: 'Circular reference detected in data' };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-syntax-003',
+  layer: LAYERS.SYNTAX,
+  severity: SEVERITY.REJECT,
+  description: 'No undefined values (use null instead)',
+  check(data) {
+    function findUndefined(obj, path = '') {
+      if (obj === undefined) return path || '(root)';
+      if (obj === null || typeof obj !== 'object') return null;
+      if (Array.isArray(obj)) {
+        for (let i = 0; i < obj.length; i++) {
+          const found = findUndefined(obj[i], `${path}[${i}]`);
+          if (found) return found;
+        }
+      } else {
+        for (const key of Object.keys(obj)) {
+          const found = findUndefined(obj[key], path ? `${path}.${key}` : key);
+          if (found) return found;
+        }
+      }
+      return null;
+    }
+    const found = findUndefined(data);
+    if (found) {
+      return { passed: false, message: `Undefined value found at: ${found}. Use null instead.` };
+    }
+    return { passed: true };
+  },
+});
+
+// --- Layer 2: Schema Conformance Rules ---
+
+registerRule({
+  id: 'rt-schema-001',
+  layer: LAYERS.SCHEMA,
+  severity: SEVERITY.REJECT,
+  description: 'Required fields must be present',
+  check(data, schema) {
+    if (!schema || !schema.required) return { passed: true };
+    const missing = [];
+    for (const field of schema.required) {
+      if (data[field] === undefined || data[field] === null) {
+        missing.push(field);
+      }
+    }
+    if (missing.length > 0) {
+      return { passed: false, message: `Missing required fields: ${missing.join(', ')}`, details: { missing } };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-schema-002',
+  layer: LAYERS.SCHEMA,
+  severity: SEVERITY.REJECT,
+  description: 'Field types must match schema',
+  check(data, schema) {
+    if (!schema || !schema.properties) return { passed: true };
+    const mismatches = [];
+    for (const [field, def] of Object.entries(schema.properties)) {
+      if (data[field] === undefined || data[field] === null) continue;
+      const expectedType = typeof def === 'string' ? def : def.type;
+      if (!expectedType) continue;
+      const actualType = Array.isArray(data[field]) ? 'array' : typeof data[field];
+      if (expectedType === 'array' && !Array.isArray(data[field])) {
+        mismatches.push({ field, expected: 'array', actual: actualType });
+      } else if (expectedType !== 'array' && actualType !== expectedType) {
+        mismatches.push({ field, expected: expectedType, actual: actualType });
+      }
+    }
+    if (mismatches.length > 0) {
+      return {
+        passed: false,
+        message: `Type mismatches: ${mismatches.map(m => `${m.field}(expected ${m.expected}, got ${m.actual})`).join(', ')}`,
+        details: { mismatches },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-schema-003',
+  layer: LAYERS.SCHEMA,
+  severity: SEVERITY.WARN,
+  description: 'Unknown fields should be flagged (strict mode)',
+  check(data, schema) {
+    if (!schema || !schema.properties || !schema.strict) return { passed: true };
+    const known = new Set(Object.keys(schema.properties));
+    const unknown = Object.keys(data).filter(k => !known.has(k));
+    if (unknown.length > 0) {
+      return {
+        passed: true, // Warning, not rejection
+        message: `Unknown fields detected: ${unknown.join(', ')}`,
+        details: { unknown },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-schema-004',
+  layer: LAYERS.SCHEMA,
+  severity: SEVERITY.REJECT,
+  description: 'String length must be within bounds',
+  check(data, schema) {
+    if (!schema || !schema.properties) return { passed: true };
+    const violations = [];
+    for (const [field, def] of Object.entries(schema.properties)) {
+      if (typeof data[field] !== 'string') continue;
+      const maxLen = typeof def === 'object' ? def.maxLength : null;
+      const minLen = typeof def === 'object' ? def.minLength : null;
+      if (maxLen && data[field].length > maxLen) {
+        violations.push({ field, issue: 'too long', max: maxLen, actual: data[field].length });
+      }
+      if (minLen && data[field].length < minLen) {
+        violations.push({ field, issue: 'too short', min: minLen, actual: data[field].length });
+      }
+    }
+    if (violations.length > 0) {
+      return { passed: false, message: `String length violations: ${JSON.stringify(violations)}`, details: { violations } };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-schema-005',
+  layer: LAYERS.SCHEMA,
+  severity: SEVERITY.REJECT,
+  description: 'Numeric values must be within range',
+  check(data, schema) {
+    if (!schema || !schema.properties) return { passed: true };
+    const violations = [];
+    for (const [field, def] of Object.entries(schema.properties)) {
+      if (typeof data[field] !== 'number') continue;
+      const max = typeof def === 'object' ? def.max : null;
+      const min = typeof def === 'object' ? def.min : null;
+      if (max !== null && data[field] > max) {
+        violations.push({ field, issue: 'exceeds max', max, actual: data[field] });
+      }
+      if (min !== null && data[field] < min) {
+        violations.push({ field, issue: 'below min', min, actual: data[field] });
+      }
+    }
+    if (violations.length > 0) {
+      return { passed: false, message: `Numeric range violations: ${JSON.stringify(violations)}`, details: { violations } };
+    }
+    return { passed: true };
+  },
+});
+
+// --- Layer 3: Semantic Rules ---
+
+registerRule({
+  id: 'rt-semantic-001',
+  layer: LAYERS.SEMANTIC,
+  severity: SEVERITY.WARN,
+  description: 'Response should have standard envelope { code, data, message }',
+  check(data, schema, ctx) {
+    if (ctx.direction !== 'response') return { passed: true };
+    if (data === null || typeof data !== 'object') return { passed: true };
+    const hasCode = 'code' in data;
+    const hasData = 'data' in data;
+    if (!hasCode || !hasData) {
+      return {
+        passed: true, // Warning
+        message: `Response missing standard envelope fields (code: ${hasCode}, data: ${hasData})`,
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-semantic-002',
+  layer: LAYERS.SEMANTIC,
+  severity: SEVERITY.WARN,
+  description: 'Response data field naming should use consistent convention (data.list not data.items/records)',
+  check(data, schema, ctx) {
+    if (ctx.direction !== 'response') return { passed: true };
+    if (!data || !data.data || typeof data.data !== 'object') return { passed: true };
+    const d = data.data;
+    // Check for inconsistent list field naming
+    const listFields = ['list', 'items', 'records', 'rows', 'results'];
+    const found = listFields.filter(f => f in d);
+    if (found.length > 1) {
+      return {
+        passed: true,
+        message: `Inconsistent list field naming: found [${found.join(', ')}]. Use 'list' consistently.`,
+        details: { found },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-semantic-003',
+  layer: LAYERS.SEMANTIC,
+  severity: SEVERITY.REJECT,
+  description: 'ID fields must not be null or empty for existing records',
+  check(data, schema, ctx) {
+    if (!data || typeof data !== 'object') return { passed: true };
+    const idFields = ['id', 'userId', 'sessionId', 'toolId'];
+    for (const field of idFields) {
+      if (field in data && (data[field] === null || data[field] === '' || data[field] === 0)) {
+        return { passed: false, message: `ID field '${field}' is null/empty for what appears to be an existing record` };
+      }
+    }
+    return { passed: true };
+  },
+});
+
+// --- Layer 4: Security Rules ---
+
+registerRule({
+  id: 'rt-security-001',
+  layer: LAYERS.SECURITY,
+  severity: SEVERITY.REJECT,
+  description: 'No SQL injection patterns in string fields',
+  check(data) {
+    const sqlPatterns = [
+      /(\bunion\b\s+\bselect\b)/i,
+      /(\bdrop\b\s+\btable\b)/i,
+      /(\bdelete\b\s+\bfrom\b.*\bwhere\b.*1=1)/i,
+      /(;\s*drop\s+table)/i,
+      /(';\s*--)/,
+    ];
+    function scanStrings(obj, path = '') {
+      const findings = [];
+      if (typeof obj === 'string') {
+        for (const pattern of sqlPatterns) {
+          if (pattern.test(obj)) {
+            findings.push({ path: path || '(root)', value: obj.substring(0, 100), pattern: pattern.source });
+          }
+        }
+      } else if (obj && typeof obj === 'object') {
+        for (const key of Object.keys(obj)) {
+          findings.push(...scanStrings(obj[key], path ? `${path}.${key}` : key));
+        }
+      }
+      return findings;
+    }
+    const findings = scanStrings(data);
+    if (findings.length > 0) {
+      return {
+        passed: false,
+        message: `Potential SQL injection detected: ${findings.length} pattern(s) found`,
+        details: { findings },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-security-002',
+  layer: LAYERS.SECURITY,
+  severity: SEVERITY.REJECT,
+  description: 'No XSS patterns in string fields',
+  check(data) {
+    const xssPatterns = [
+      /<script[^>]*>[\s\S]*?<\/script>/i,
+      /javascript:/i,
+      /on\w+\s*=\s*["'][^"']*["']/i,
+      /<iframe[^>]*>/i,
+    ];
+    function scanStrings(obj, path = '') {
+      const findings = [];
+      if (typeof obj === 'string') {
+        for (const pattern of xssPatterns) {
+          if (pattern.test(obj)) {
+            findings.push({ path: path || '(root)', value: obj.substring(0, 100) });
+          }
+        }
+      } else if (obj && typeof obj === 'object') {
+        for (const key of Object.keys(obj)) {
+          findings.push(...scanStrings(obj[key], path ? `${path}.${key}` : key));
+        }
+      }
+      return findings;
+    }
+    const findings = scanStrings(data);
+    if (findings.length > 0) {
+      return {
+        passed: false,
+        message: `Potential XSS detected: ${findings.length} pattern(s) found`,
+        details: { findings },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-security-003',
+  layer: LAYERS.SECURITY,
+  severity: SEVERITY.REJECT,
+  description: 'No path traversal patterns',
+  check(data) {
+    function scanStrings(obj, path = '') {
+      const findings = [];
+      if (typeof obj === 'string') {
+        if (/\.\.[\/\\]/.test(obj) || /\.\.%2f/i.test(obj) || /\.\.%5c/i.test(obj)) {
+          findings.push({ path: path || '(root)', value: obj.substring(0, 100) });
+        }
+      } else if (obj && typeof obj === 'object') {
+        for (const key of Object.keys(obj)) {
+          findings.push(...scanStrings(obj[key], path ? `${path}.${key}` : key));
+        }
+      }
+      return findings;
+    }
+    const findings = scanStrings(data);
+    if (findings.length > 0) {
+      return {
+        passed: false,
+        message: `Path traversal pattern detected`,
+        details: { findings },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-security-004',
+  layer: LAYERS.SECURITY,
+  severity: SEVERITY.WARN,
+  description: 'Sensitive fields should not be exposed in responses',
+  check(data, schema, ctx) {
+    if (ctx.direction !== 'response') return { passed: true };
+    if (!data || typeof data !== 'object') return { passed: true };
+    const sensitiveFields = ['password', 'secret', 'token', 'apiKey', 'privateKey', 'creditCard'];
+    function findSensitive(obj, path = '') {
+      const found = [];
+      if (obj && typeof obj === 'object') {
+        for (const key of Object.keys(obj)) {
+          if (sensitiveFields.some(s => key.toLowerCase().includes(s.toLowerCase()))) {
+            found.push(path ? `${path}.${key}` : key);
+          }
+          found.push(...findSensitive(obj[key], path ? `${path}.${key}` : key));
+        }
+      }
+      return found;
+    }
+    const found = findSensitive(data);
+    if (found.length > 0) {
+      return {
+        passed: true, // Warning
+        message: `Sensitive fields exposed in response: ${found.join(', ')}`,
+        details: { fields: found },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+registerRule({
+  id: 'rt-security-005',
+  layer: LAYERS.SECURITY,
+  severity: SEVERITY.REJECT,
+  description: 'No command injection patterns',
+  check(data) {
+    const cmdPatterns = [
+      /(\|\s*\w+)/,          // Pipe to command
+      /(`[^`]*`)/,            // Backtick command substitution
+      /(\$\([^)]*\))/,        // $() command substitution
+      /(&&\s*\w+)/,           // && chaining
+      /(;\s*\w+\s+)/,         // Semicolon command chaining
+    ];
+    function scanStrings(obj, path = '') {
+      const findings = [];
+      if (typeof obj === 'string' && obj.length < 1000) { // Skip very long strings
+        for (const pattern of cmdPatterns) {
+          if (pattern.test(obj)) {
+            findings.push({ path: path || '(root)', value: obj.substring(0, 100), pattern: pattern.source });
+          }
+        }
+      } else if (obj && typeof obj === 'object') {
+        for (const key of Object.keys(obj)) {
+          findings.push(...scanStrings(obj[key], path ? `${path}.${key}` : key));
+        }
+      }
+      return findings;
+    }
+    const findings = scanStrings(data);
+    if (findings.length > 0) {
+      return {
+        passed: false,
+        message: `Potential command injection: ${findings.length} pattern(s) found`,
+        details: { findings },
+      };
+    }
+    return { passed: true };
+  },
+});
+
+// ============ SchemaGatekeeper ============
+
+class SchemaGatekeeper {
+  constructor(opts = {}) {
+    this._rules = [...RULES];
+    this._strict = opts.strict !== false; // Default: strict mode
+    this._enabledLayers = opts.enabledLayers || Object.values(LAYERS);
+    this._stats = {
+      totalChecks: 0,
+      totalPassed: 0,
+      totalRejected: 0,
+      totalWarnings: 0,
+    };
+    this._rejectHistory = [];
+    this._maxHistory = 50;
+  }
+
+  /**
+   * Validate data against a schema through all 4 defense layers.
+   *
+   * @param {object} data - Data to validate
+   * @param {object} schema - Schema definition (JSON-schema-like)
+   * @param {object} ctx - Context { direction: 'request'|'response', action, toolId }
+   * @returns {object} { passed, warnings, rejections, details }
+   */
+  validate(data, schema = null, ctx = {}) {
+    this._stats.totalChecks++;
+
+    const warnings = [];
+    const rejections = [];
+    const layerResults = {};
+
+    for (const rule of this._rules) {
+      // Skip disabled layers
+      if (!this._enabledLayers.includes(rule.layer)) continue;
+
+      let result;
+      try {
+        result = rule.check(data, schema, ctx);
+      } catch (err) {
+        result = { passed: false, message: `Rule '${rule.id}' error: ${err.message}` };
+      }
+
+      layerResults[rule.id] = {
+        layer: rule.layer,
+        severity: rule.severity,
+        passed: result.passed,
+        message: result.message || null,
+      };
+
+      if (result.passed) {
+        if (result.message) {
+          warnings.push({ ruleId: rule.id, layer: rule.layer, message: result.message, details: result.details });
+        }
+      } else {
+        if (rule.severity === SEVERITY.REJECT) {
+          rejections.push({ ruleId: rule.id, layer: rule.layer, message: result.message, details: result.details });
+        } else {
+          warnings.push({ ruleId: rule.id, layer: rule.layer, message: result.message, details: result.details });
+        }
+      }
+    }
+
+    const passed = rejections.length === 0;
+
+    if (passed) {
+      this._stats.totalPassed++;
+      if (warnings.length > 0) {
+        this._stats.totalWarnings++;
+      }
+    } else {
+      this._stats.totalRejected++;
+      this._rejectHistory.push({
+        ts: Date.now(),
+        ctx,
+        rejections: rejections.map(r => ({ ruleId: r.ruleId, message: r.message })),
+      });
+      if (this._rejectHistory.length > this._maxHistory) {
+        this._rejectHistory.shift();
+      }
+    }
+
+    // Emit event
+    bus.emit('gatekeeper:validated', {
+      passed,
+      warningCount: warnings.length,
+      rejectionCount: rejections.length,
+      ctx,
+    });
+
+    if (!passed) {
+      log.warn(`验证被拒绝：${rejections.map(r => r.message).join('; ')}`);
+    }
+
+    return { passed, warnings, rejections, details: layerResults };
+  }
+
+  /**
+   * Validate a tool input before invocation.
+   */
+  validateInput(data, schema, ctx = {}) {
+    return this.validate(data, schema, { ...ctx, direction: 'request' });
+  }
+
+  /**
+   * Validate a tool output before returning to client.
+   */
+  validateOutput(data, schema, ctx = {}) {
+    return this.validate(data, schema, { ...ctx, direction: 'response' });
+  }
+
+  /**
+   * Quick check — only runs syntax and security layers (fast path).
+   */
+  quickCheck(data, ctx = {}) {
+    const fastLayers = [LAYERS.SYNTAX, LAYERS.SECURITY];
+    const original = this._enabledLayers;
+    this._enabledLayers = fastLayers;
+    const result = this.validate(data, null, ctx);
+    this._enabledLayers = original;
+    return result;
+  }
+
+  /**
+   * Add a custom rule.
+   */
+  addRule(rule) {
+    registerRule(rule);
+    this._rules.push(rule);
+  }
+
+  /**
+   * Get stats.
+   */
+  getStats() {
+    return {
+      ...this._stats,
+      passRate: this._stats.totalChecks > 0
+        ? Math.round((this._stats.totalPassed / this._stats.totalChecks) * 1000) / 10
+        : 100,
+      ruleCount: this._rules.length,
+      layers: this._enabledLayers,
+    };
+  }
+
+  /**
+   * Get recent rejections.
+   */
+  getRejectHistory(limit) {
+    if (limit) return this._rejectHistory.slice(-limit);
+    return this._rejectHistory.slice();
+  }
+
+  /**
+   * List all registered rules.
+   */
+  listRules() {
+    return this._rules.map(r => ({
+      id: r.id,
+      layer: r.layer,
+      severity: r.severity,
+      description: r.description,
+    }));
+  }
+}
+
+// Singleton
+const gatekeeper = new SchemaGatekeeper();
+
+module.exports = { SchemaGatekeeper, gatekeeper, LAYERS, SEVERITY, registerRule, RULES };