agent-master-devsecops 0.0.0-stage → 5.1.0

package/scripts/core/knowledge_gateway.js

@@ -0,0 +1,888 @@
+/**
+ * scripts/core/knowledge_gateway.js
+ * 
+ * Dynamic Knowledge Gateway & Authoritative API Augmentation (v5.0 Enterprise).
+ * Grounding vivo em documentações e APIs oficiais (W3C, OSV.dev, Spring Initializr, DevDocs, Endoflife.date).
+ * 
+ * Arquitetura Tri-Tier:
+ * - Tier 1: Authoritative Live APIs (OSV.dev CVEs, Spring Initializr, W3C Specs) com Circuit Breakers.
+ * - Tier 2: Local Hot Cache persistente via SQLite WAL (sub-milissegundo).
+ * - Tier 3: Catálogo Determinístico Embutido de Contingência Offline (Infalível).
+ * 
+ * Blindagem de Segurança:
+ * - Zero Egress Data Leakage Guardrail (veto pré-flight de tokens, credenciais, emails e código).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const https = require('node:https');
+const http = require('node:http');
+const { CircuitBreaker } = require('./circuit_breaker.js');
+
+// ==========================================
+// TIER 3: Catálogo de Contingência Offline
+// ==========================================
+
+const OFFLINE_CVE_CATALOG = [
+  {
+    package: 'lodash',
+    ecosystem: 'npm',
+    affectedVersionRegex: /^([0-3]\.|4\.(0|1[0-6]\.|17\.[0-9]\b|17\.1[0-9]\b|17\.20\b))/,
+    cve: 'CVE-2020-8203',
+    severity: 'ALTA',
+    summary: 'Prototype Pollution em zipObjectDeep e defaultsDeep',
+    fixedVersion: '4.17.21',
+    recommendation: 'Atualize para lodash >= 4.17.21'
+  },
+  {
+    package: 'axios',
+    ecosystem: 'npm',
+    affectedVersionRegex: /^(0\.(1[0-9]\.|2[0-1]\.[0-1]\b))/,
+    cve: 'CVE-2020-28168',
+    severity: 'ALTA',
+    summary: 'Server-Side Request Forgery (SSRF) e vazamento de cabeçalho Authorization em redirects',
+    fixedVersion: '0.21.2',
+    recommendation: 'Atualize para axios >= 0.21.2 ou >= 1.x'
+  },
+  {
+    package: 'tar',
+    ecosystem: 'npm',
+    affectedVersionRegex: /^([0-5]\.|6\.(0\.|1\.[0-8]\b))/,
+    cve: 'CVE-2021-37712',
+    severity: 'ALTA',
+    summary: 'Path Traversal e sobrescrita arbitrária de arquivos durante extração de tarballs',
+    fixedVersion: '6.1.9',
+    recommendation: 'Atualize para tar >= 6.1.9'
+  },
+  {
+    package: 'minimist',
+    ecosystem: 'npm',
+    affectedVersionRegex: /^([0-1]\.(0\.|1\.|2\.[0-5]\b))/,
+    cve: 'CVE-2020-7598',
+    severity: 'MÉDIA',
+    summary: 'Prototype Pollution via argumentos de linha de comando',
+    fixedVersion: '1.2.6',
+    recommendation: 'Atualize para minimist >= 1.2.6'
+  },
+  {
+    package: 'shell-quote',
+    ecosystem: 'npm',
+    affectedVersionRegex: /^(1\.[0-6]\.|1\.7\.[0-2]\b)/,
+    cve: 'CVE-2021-42740',
+    severity: 'CRÍTICA',
+    summary: 'Command Injection (CWE-78) via caracteres de escape mal formatados',
+    fixedVersion: '1.7.3',
+    recommendation: 'Atualize para shell-quote >= 1.7.3'
+  },
+  {
+    package: 'log4j-core',
+    ecosystem: 'Maven',
+    affectedVersionRegex: /^(2\.(0|1[0-6]\.|17\.0\b))/,
+    cve: 'CVE-2021-44228',
+    severity: 'CRÍTICA',
+    summary: 'Log4Shell - Remote Code Execution (RCE) via JNDI injection',
+    fixedVersion: '2.17.1',
+    recommendation: 'Atualize para org.apache.logging.log4j:log4j-core >= 2.17.1'
+  },
+  {
+    package: 'spring-beans',
+    ecosystem: 'Maven',
+    affectedVersionRegex: /^(5\.(3\.[0-9]\b|3\.1[0-7]\b))/,
+    cve: 'CVE-2022-22965',
+    severity: 'CRÍTICA',
+    summary: 'Spring4Shell - Remote Code Execution via ClassLoader access',
+    fixedVersion: '5.3.18',
+    recommendation: 'Atualize para Spring Framework >= 5.3.18 ou Spring Boot >= 3.0'
+  }
+];
+
+const OFFLINE_WCAG_RULES = [
+  {
+    id: 'WCAG-1.1.1',
+    criterion: 'Non-text Content (Nível A)',
+    name: 'Imagem sem texto alternativo (alt)',
+    severity: 'CRÍTICA',
+    pattern: /<(?:img|Image)\b(?![^>]*\balt\s*=)[^>]*>/i,
+    issue: 'Elemento de imagem não possui o atributo "alt" para tecnologias assistivas.',
+    remediation: 'Adicione alt="Descrição da imagem" ou alt="" acompanhado de role="presentation" para imagens puramente decorativas.',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html'
+  },
+  {
+    id: 'WCAG-4.1.2-BTN',
+    criterion: 'Name, Role, Value (Nível A)',
+    name: 'Botão interativo sem rótulo acessível',
+    severity: 'ALTA',
+    pattern: /<(?:button)\b(?![^>]*\b(?:aria-label|aria-labelledby|title)\s*=)[^>]*>\s*<(?:svg|i|span)\b[^>]*>\s*<\/(?:svg|i|span)>\s*<\/button>/i,
+    issue: 'Botão contendo apenas ícone sem aria-label, aria-labelledby ou texto acessível.',
+    remediation: 'Inclua aria-label="Ação do botão" ou texto acessível visível/oculto via classe sr-only.',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html'
+  },
+  {
+    id: 'WCAG-1.3.1-INPUT',
+    criterion: 'Info and Relationships (Nível A)',
+    name: 'Campo de entrada (input) sem rótulo associado',
+    severity: 'CRÍTICA',
+    pattern: /<(?:input)\b(?![^>]*\b(?:type=["'](?:hidden|submit|button|image)["']))(?![^>]*\b(?:aria-label|aria-labelledby|id\s*=))[^>]*>/i,
+    issue: 'Elemento <input> não possui id para pareamento com <label htmlFor="..."> nem aria-label.',
+    remediation: 'Adicione um id único ao input pareado com <label htmlFor="id"> ou declare aria-label.',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html'
+  },
+  {
+    id: 'WCAG-2.4.4-LINK',
+    criterion: 'Link Purpose (In Context) (Nível A)',
+    name: 'Link com texto vago ou não descritivo',
+    severity: 'MÉDIA',
+    pattern: /<a\b[^>]*>\s*(?:clique aqui|click here|saiba mais|read more|veja mais|link)\s*<\/a>/i,
+    issue: 'Texto de link ambíguo ("clique aqui", "saiba mais") que prejudica a navegação cega por links.',
+    remediation: 'Substitua por texto descritivo do destino (ex: "Consulte o catálogo de livros").',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html'
+  },
+  {
+    id: 'WCAG-2.4.7-FOCUS',
+    criterion: 'Focus Visible (Nível AA)',
+    name: 'Supressão de contorno de foco sem anel acessível',
+    severity: 'ALTA',
+    pattern: /className=["'][^"']*\boutline-none\b(?![^"']*\b(?:focus-visible:|focus:ring|focus:border))[^"']*["']/i,
+    issue: 'Uso de outline-none sem definição de anel alternativo de foco (focus-visible / focus:ring).',
+    remediation: 'Mantenha o foco visível para usuários de teclado adicionando classes como "focus-visible:ring-2 focus-visible:ring-blue-500".',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html'
+  },
+  {
+    id: 'WCAG-2.4.3-TABINDEX',
+    criterion: 'Focus Order (Nível A)',
+    name: 'Uso de tabindex positivo (anti-pattern)',
+    severity: 'MÉDIA',
+    pattern: /\btabIndex\s*=\s*(?:\{[1-9][0-9]*\}|["'][1-9][0-9]*["'])/i,
+    issue: 'tabindex maior que zero altera a ordem natural de tabulação do DOM.',
+    remediation: 'Utilize tabindex="0" para incluir o elemento no fluxo natural ou reorganize a ordem dos elementos no DOM.',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html'
+  },
+  {
+    id: 'WCAG-3.1.1-LANG',
+    criterion: 'Language of Page (Nível A)',
+    name: 'Documento HTML sem atributo de idioma (lang)',
+    severity: 'ALTA',
+    pattern: /<html\b(?![^>]*\blang\s*=)[^>]*>/i,
+    issue: 'Tag <html> sem atributo lang, impedindo sintetizadores de voz de carregar a pronúncia correta.',
+    remediation: 'Declare o idioma principal do documento: <html lang="pt-BR">.',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html'
+  },
+  {
+    id: 'WCAG-4.1.2-EXPANDED',
+    criterion: 'Name, Role, Value (Nível A)',
+    name: 'Elemento colapsável/dropdown sem aria-expanded',
+    severity: 'ALTA',
+    pattern: /<(?:button|summary)\b[^>]*\b(?:data-toggle|dropdown|accordion)[^>]*>(?![^>]*\baria-expanded\s*=)/i,
+    issue: 'Elemento com comportamento de toggle/acordeão sem declaração explícita de estado via aria-expanded.',
+    remediation: 'Declare aria-expanded="true" ou aria-expanded="false" atualizado via estado.',
+    authoritativeRef: 'https://www.w3.org/WAI/ARIA/apg/patterns/accordion/'
+  },
+  {
+    id: 'WCAG-4.1.3-LIVE',
+    criterion: 'Status Messages (Nível AA)',
+    name: 'Alertas dinâmicos ou mensagens de erro sem aria-live',
+    severity: 'MÉDIA',
+    pattern: /<(?:div|section)\b[^>]*\bclass(?:Name)?=["'][^"']*\b(?:alert|toast|notification)\b[^"']*["'](?![^>]*\b(?:role=["'](?:alert|status)["']|aria-live\s*=))[^>]*>/i,
+    issue: 'Componente de alerta/notificação dinâmica sem role="alert" ou aria-live="polite".',
+    remediation: 'Adicione role="alert" para avisos imediatos ou aria-live="polite" para mensagens de status.',
+    authoritativeRef: 'https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html'
+  }
+];
+
+const OFFLINE_RUNTIME_LTS = {
+  java: {
+    tech: 'Java (OpenJDK)',
+    recommendedVersion: '21',
+    activeLtsVersions: ['21', '17'],
+    unsupportedVersions: ['8', '11', '14', '15', '16', '18', '19', '20'],
+    nextLtsVersion: '25',
+    latestLtsDetails: {
+      version: '21',
+      codename: 'Java 21 LTS',
+      features: [
+        'Virtual Threads (Project Loom - JEP 444)',
+        'Record Patterns (JEP 440)',
+        'Pattern Matching for switch (JEP 441)',
+        'Sequenced Collections (JEP 431)',
+        'Foreign Function & Memory API (Preview)'
+      ],
+      architecturalGuidance: 'Para sistemas de alto throughput e microsserviços modernos, configure Virtual Threads em vez de thread pool tradicional (Executors.newVirtualThreadPerTaskExecutor) e use Java Records para DTOs imutáveis.'
+    }
+  },
+  nodejs: {
+    tech: 'Node.js',
+    recommendedVersion: '22',
+    activeLtsVersions: ['22', '20'],
+    unsupportedVersions: ['14', '16', '18'],
+    latestLtsDetails: {
+      version: '22',
+      features: [
+        'Native SQLite module (node:sqlite)',
+        'Native TypeScript strip-types (--experimental-strip-types)',
+        'Native Test Runner (node:test)',
+        'Native WebSocket client'
+      ]
+    }
+  },
+  golang: {
+    tech: 'Go (Golang)',
+    recommendedVersion: '1.23',
+    activeLtsVersions: ['1.23', '1.22'],
+    unsupportedVersions: ['1.19', '1.20', '1.21'],
+    latestLtsDetails: {
+      version: '1.23',
+      features: [
+        'Range over function iterators',
+        'Structured logging (log/slog)',
+        'Enhanced routing (net/http enhanced mux)',
+        'Type parameters (Generics)'
+      ]
+    }
+  },
+  python: {
+    tech: 'Python',
+    recommendedVersion: '3.12',
+    activeLtsVersions: ['3.12', '3.13'],
+    unsupportedVersions: ['3.7', '3.8', '3.9'],
+    latestLtsDetails: {
+      version: '3.12',
+      features: [
+        'Type parameter syntax (PEP 695)',
+        'Isolated subinterpreters (PEP 684)',
+        'Low-impact monitoring & performance boosts'
+      ]
+    }
+  },
+  spring_boot: {
+    tech: 'Spring Boot',
+    recommendedVersion: '3.3',
+    activeLtsVersions: ['3.3', '3.2'],
+    unsupportedVersions: ['2.7', '2.6', '2.5', '1.5'],
+    latestLtsDetails: {
+      version: '3.3',
+      requiresJava: '>= 17 (Recommended: 21)',
+      baseline: 'Jakarta EE 10',
+      features: [
+        'Virtual Threads support (spring.threads.virtual.enabled=true)',
+        'Spring Security 6 with Method Security',
+        'Spring Data JPA with Hibernate 6.5',
+        'Observability first-class with Micrometer & OpenTelemetry'
+      ]
+    }
+  }
+};
+
+// ==========================================
+// EGRESS GUARDRAIL (Zero Data Leakage)
+// ==========================================
+
+const EGRESS_PATTERNS = [
+  { name: 'API_KEY_OPENAI', regex: /sk-[a-zA-Z0-9_-]{20,}/i },
+  { name: 'API_KEY_GITHUB', regex: /gh[pousr]_[a-zA-Z0-9]{20,}/i },
+  { name: 'API_KEY_AWS', regex: /AKIA[0-9A-Z]{16}/ },
+  { name: 'JWT_BEARER_TOKEN', regex: /eyJ[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{20,}/ },
+  { name: 'PRIVATE_KEY', regex: /-----BEGIN[ A-Z0-9_-]*PRIVATE KEY-----/i },
+  { name: 'CREDENTIAL_ASSIGNMENT', regex: /(?:password|passwd|secret|api_key|app_secret|auth_token)\s*[:=]\s*["']?[^"'\s]{4,}/i },
+  { name: 'EMAIL_ADDRESS', regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/ }
+];
+
+function inspectEgress(payload) {
+  const str = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  const violations = [];
+
+  for (const pattern of EGRESS_PATTERNS) {
+    if (pattern.regex.test(str)) {
+      violations.push(pattern.name);
+    }
+  }
+
+  // Prevenção de vazamento de arquivos de código fonte brutos para fora da máquina
+  const lines = str.split('\n');
+  const hasCodeSyntax = /\b(function|class|interface|import\s+.*from|public\s+class|def\s+\w+|fn\s+\w+|child_process|execSync)\b/.test(str);
+  if (lines.length >= 3 && hasCodeSyntax) {
+    violations.push('MULTILINE_SOURCE_CODE_BODY');
+  }
+
+  return {
+    safe: violations.length === 0,
+    violations
+  };
+}
+
+// ==========================================
+// CLASSE PRINCIPAL: KnowledgeGateway
+// ==========================================
+
+class KnowledgeGateway {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.offlineMode = Boolean(options.offlineMode || process.env.OFFLINE_MODE === '1');
+    this.timeoutMs = options.timeoutMs || 2500;
+    this.transportAdapter = options.transportAdapter || null;
+    this.cacheTtlMs = options.cacheTtlMs || (24 * 60 * 60 * 1000); // 24h padrão
+    
+    // Circuit Breakers por domínio para proteção contra falhas em cascata
+    this.circuits = {
+      osv: new CircuitBreaker('api.osv.dev', { failureThreshold: options.failureThreshold || 3, recoveryTimeoutMs: options.recoveryTimeoutMs || 30000 }),
+      spring: new CircuitBreaker('start.spring.io', { failureThreshold: options.failureThreshold || 3, recoveryTimeoutMs: options.recoveryTimeoutMs || 30000 }),
+      eol: new CircuitBreaker('endoflife.date', { failureThreshold: options.failureThreshold || 3, recoveryTimeoutMs: options.recoveryTimeoutMs || 30000 })
+    };
+
+    // Inicialização do Cache Local (Tier 2 - SQLite WAL)
+    this.db = null;
+    this.memoryCache = new Map();
+    this.storagePath = options.storagePath || path.join(this.rootDir, '.cache', 'knowledge_cache.db');
+    this._initDatabase(this.storagePath);
+  }
+
+  _initDatabase(dbPath) {
+    try {
+      const { DatabaseSync } = require('node:sqlite');
+      if (dbPath && dbPath !== ':memory:') {
+        const dir = path.dirname(dbPath);
+        if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        this.db = new DatabaseSync(dbPath);
+      } else {
+        this.db = new DatabaseSync(':memory:');
+      }
+
+      this.db.exec(`
+        PRAGMA journal_mode = WAL;
+        PRAGMA synchronous = NORMAL;
+        CREATE TABLE IF NOT EXISTS knowledge_cache (
+          query_hash TEXT PRIMARY KEY,
+          category TEXT NOT NULL,
+          query_key TEXT NOT NULL,
+          response_json TEXT NOT NULL,
+          etag TEXT,
+          created_at INTEGER NOT NULL,
+          expires_at INTEGER NOT NULL,
+          source TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_cat_key ON knowledge_cache (category, query_key);
+      `);
+    } catch (err) {
+      void err;
+      this.db = null;
+    }
+  }
+
+  _computeHash(str) {
+    return crypto.createHash('sha256').update(str).digest('hex');
+  }
+
+  // ==========================================
+  // OPERAÇÕES DE CACHE (Tier 2)
+  // ==========================================
+
+  getCached(category, queryKey) {
+    const hash = this._computeHash(`${category}:${queryKey}`);
+    const now = Date.now();
+
+    if (this.db) {
+      try {
+        const stmt = this.db.prepare('SELECT response_json, expires_at, source FROM knowledge_cache WHERE query_hash = ?');
+        const row = stmt.get(hash);
+        if (row) {
+          const isExpired = now > row.expires_at;
+          const parsed = JSON.parse(row.response_json);
+          return {
+            found: true,
+            isExpired,
+            data: parsed,
+            source: row.source
+          };
+        }
+      } catch (err) {
+        void err;
+      }
+    }
+
+    if (this.memoryCache.has(hash)) {
+      const entry = this.memoryCache.get(hash);
+      return {
+        found: true,
+        isExpired: now > entry.expiresAt,
+        data: entry.data,
+        source: entry.source
+      };
+    }
+
+    return { found: false, isExpired: false, data: null };
+  }
+
+  setCached(category, queryKey, data, source = 'live_api', customTtlMs = null) {
+    const hash = this._computeHash(`${category}:${queryKey}`);
+    const now = Date.now();
+    const expiresAt = now + (customTtlMs || this.cacheTtlMs);
+    const jsonStr = JSON.stringify(data);
+
+    if (this.db) {
+      try {
+        const stmt = this.db.prepare(`
+          INSERT INTO knowledge_cache (query_hash, category, query_key, response_json, etag, created_at, expires_at, source)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(query_hash) DO UPDATE SET
+            response_json = excluded.response_json,
+            expires_at = excluded.expires_at,
+            source = excluded.source;
+        `);
+        stmt.run(hash, category, queryKey, jsonStr, null, now, expiresAt, source);
+      } catch (err) {
+        void err;
+      }
+    }
+
+    this.memoryCache.set(hash, {
+      data,
+      expiresAt,
+      source
+    });
+  }
+
+  // ==========================================
+  // CLIENTE HTTP RESILIENTE COM TIMEOUT
+  // ==========================================
+
+  async _fetchHttpJson(urlStr, options = {}) {
+    if (this.transportAdapter) {
+      return this.transportAdapter(urlStr, options);
+    }
+
+    const timeoutMs = options.timeoutMs || this.timeoutMs;
+    const parsed = new URL(urlStr);
+    const transport = parsed.protocol === 'https:' ? https : http;
+
+    return new Promise((resolve, reject) => {
+      const headers = {
+        'Accept': 'application/json',
+        'User-Agent': 'Agent-Master-DevSecOps/5.0 (KnowledgeGateway; Enterprise)',
+        ...(options.headers || {})
+      };
+
+      let postData = null;
+      if (options.body) {
+        postData = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
+        headers['Content-Type'] = 'application/json';
+        headers['Content-Length'] = Buffer.byteLength(postData);
+      }
+
+      const req = transport.request(parsed, {
+        method: options.method || (options.body ? 'POST' : 'GET'),
+        headers,
+        timeout: timeoutMs
+      }, (res) => {
+        let rawData = '';
+        res.setEncoding('utf8');
+        res.on('data', chunk => { rawData += chunk; });
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            try {
+              const parsedJson = JSON.parse(rawData);
+              resolve({ statusCode: res.statusCode, data: parsedJson });
+            } catch (err) {
+              void err;
+              resolve({ statusCode: res.statusCode, raw: rawData });
+            }
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}: ${res.statusMessage || 'API error'}`));
+          }
+        });
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error(`Timeout de rede após ${timeoutMs}ms para ${urlStr}`));
+      });
+
+      req.on('error', (err) => {
+        reject(err);
+      });
+
+      if (postData) {
+        req.write(postData);
+      }
+      req.end();
+    });
+  }
+
+  // ==========================================
+  // SERVIÇO 1: Consulta de Vulnerabilidades OSV.dev
+  // ==========================================
+
+  async queryOsv(packageName, version, ecosystem = 'npm') {
+    const queryKey = `${ecosystem}:${packageName}@${version || 'latest'}`;
+
+    // Verificação de Egress Guardrail
+    const egress = inspectEgress(queryKey);
+    if (!egress.safe) {
+      return {
+        found: false,
+        blocked: true,
+        reason: 'EGRESS_BLOCKED',
+        violations: egress.violations,
+        vulnerabilities: [],
+        source: 'guardrail_veto',
+        tier: 0
+      };
+    }
+
+    // 1. Tenta Cache Local Quente (Tier 2)
+    const cached = this.getCached('osv', queryKey);
+    if (cached.found && !cached.isExpired) {
+      return {
+        ...cached.data,
+        source: 'local_hot_cache',
+        tier: 2
+      };
+    }
+
+    // 2. Tenta API Oficial OSV.dev (Tier 1) se online e circuito fechado
+    if (!this.offlineMode && !this.circuits.osv.isOpen()) {
+      try {
+        const liveRes = await this.circuits.osv.execute(async () => {
+          const bodyPayload = {
+            package: { name: packageName, ecosystem },
+            version: version || undefined
+          };
+          return this._fetchHttpJson('https://api.osv.dev/v1/query', { body: bodyPayload });
+        });
+
+        if (liveRes.result && liveRes.result.data) {
+          const vulns = liveRes.result.data.vulns || [];
+          const normalizedVulns = vulns.map(v => {
+            const cves = (v.aliases || []).filter(a => a.startsWith('CVE-'));
+            const cveStr = cves.length > 0 ? cves.join(', ') : (v.id || 'Advisory');
+            let severity = 'ALTA';
+            if (v.severity && Array.isArray(v.severity)) {
+              const score = v.severity[0]?.score;
+              if (score && typeof score === 'string' && score.includes('CVSS:3')) {
+                severity = 'CRÍTICA';
+              }
+            }
+            return {
+              id: v.id,
+              cve: cveStr,
+              severity,
+              summary: v.summary || v.details?.substring(0, 150) || 'Vulnerabilidade reportada no OSV',
+              recommendation: `Atualize ${packageName} para a versão corrigida documentada em https://osv.dev/vulnerability/${v.id}`
+            };
+          });
+
+          const resultPayload = {
+            package: packageName,
+            version,
+            ecosystem,
+            hasVulnerabilities: normalizedVulns.length > 0,
+            vulnerabilitiesCount: normalizedVulns.length,
+            vulnerabilities: normalizedVulns,
+            source: 'osv_live_api',
+            tier: 1
+          };
+
+          this.setCached('osv', queryKey, resultPayload, 'osv_live_api');
+          return resultPayload;
+        }
+      } catch (err) {
+        void err;
+        // Falha na live API: prossegue para contingência
+      }
+    }
+
+    // Se tiver cache expirado (Stale-While-Revalidate), entrega em vez de quebrar
+    if (cached.found) {
+      return {
+        ...cached.data,
+        stale: true,
+        source: 'stale_cache_contingency',
+        tier: 2
+      };
+    }
+
+    // 3. Fallback Determinístico Embutido (Tier 3)
+    const rawVer = String(version || '').replace(/^[\^~>=<]+/, '').trim();
+    const matches = OFFLINE_CVE_CATALOG.filter(c => {
+      if (c.package.toLowerCase() !== packageName.toLowerCase()) return false;
+      if (c.ecosystem.toLowerCase() !== ecosystem.toLowerCase()) return false;
+      return c.affectedVersionRegex.test(rawVer);
+    });
+
+    const fallbackVulns = matches.map(m => ({
+      id: m.cve,
+      cve: m.cve,
+      severity: m.severity,
+      summary: m.summary,
+      recommendation: m.recommendation
+    }));
+
+    return {
+      package: packageName,
+      version,
+      ecosystem,
+      hasVulnerabilities: fallbackVulns.length > 0,
+      vulnerabilitiesCount: fallbackVulns.length,
+      vulnerabilities: fallbackVulns,
+      source: 'embedded_offline_catalog',
+      tier: 3
+    };
+  }
+
+  // ==========================================
+  // SERVIÇO 2: Diretrizes & Especificações WCAG / WAI-ARIA
+  // ==========================================
+
+  getWcagSpec(criterionOrRuleId) {
+    if (!criterionOrRuleId) return null;
+    const q = String(criterionOrRuleId).toLowerCase();
+    return OFFLINE_WCAG_RULES.find(r => r.id.toLowerCase() === q || r.name.toLowerCase().includes(q)) || null;
+  }
+
+  getAllWcagRules() {
+    return [...OFFLINE_WCAG_RULES];
+  }
+
+  // ==========================================
+  // SERVIÇO 3: Blueprint Spring Boot / Java 21 LTS
+  // ==========================================
+
+  async getSpringBlueprint(spec = {}) {
+    const domain = (spec.domain || spec.name || 'app').toLowerCase();
+    const pkg = spec.package || `com.empresa.${domain}`;
+    const bootVersion = spec.bootVersion || '3.3.4';
+    const javaVersion = spec.javaVersion || '21';
+    const queryKey = `spring:${domain}:${bootVersion}:${javaVersion}`;
+
+    // Cache lookup
+    const cached = this.getCached('spring_blueprint', queryKey);
+    if (cached.found && !cached.isExpired) {
+      return { ...cached.data, tier: 2 };
+    }
+
+    // Tentativa online em start.spring.io (Tier 1) para checar versões mais recentes
+    let latestBoot = bootVersion;
+    if (!this.offlineMode && !this.circuits.spring.isOpen()) {
+      try {
+        const metadata = await this.circuits.spring.execute(async () => {
+          return this._fetchHttpJson('https://start.spring.io/metadata/client', {
+            headers: { 'Accept': 'application/vnd.initializr.v2.2+json' }
+          });
+        });
+        if (metadata.result?.data?.bootVersion?.default) {
+          latestBoot = metadata.result.data.bootVersion.default;
+        }
+      } catch (err) {
+        void err;
+      }
+    }
+
+    const blueprint = {
+      javaVersion,
+      bootVersion: latestBoot,
+      jakartaVersion: '10',
+      virtualThreadsConfig: 'spring.threads.virtual.enabled=true',
+      recommendedDependencies: [
+        'org.springframework.boot:spring-boot-starter-web',
+        'org.springframework.boot:spring-boot-starter-data-jpa',
+        'org.springframework.boot:spring-boot-starter-validation',
+        'org.springframework.boot:spring-boot-starter-actuator',
+        'org.springframework.boot:spring-boot-starter-security'
+      ],
+      architecturalPatterns: [
+        'Java 21 Records para DTOs imutáveis de alta performance',
+        'Virtual Threads (Project Loom) nativos para escalabilidade de I/O bloqueante',
+        'Spring Security 6 com CSRF e Rate Limiting explícitos',
+        'Jakarta Validation 3.0 para garantia de invariantes de domínio em runtime'
+      ],
+      pomDependenciesSnippet: [
+        `        <dependency>`,
+        `            <groupId>org.springframework.boot</groupId>`,
+        `            <artifactId>spring-boot-starter-web</artifactId>`,
+        `        </dependency>`,
+        `        <dependency>`,
+        `            <groupId>org.springframework.boot</groupId>`,
+        `            <artifactId>spring-boot-starter-data-jpa</artifactId>`,
+        `        </dependency>`,
+        `        <dependency>`,
+        `            <groupId>org.springframework.boot</groupId>`,
+        `            <artifactId>spring-boot-starter-validation</artifactId>`,
+        `        </dependency>`,
+        `        <dependency>`,
+        `            <groupId>org.springframework.boot</groupId>`,
+        `            <artifactId>spring-boot-starter-actuator</artifactId>`,
+        `        </dependency>`
+      ].join('\n'),
+      applicationPropertiesSnippet: [
+        `# Configuração Enterprise Java 21 LTS + Spring Boot ${latestBoot}`,
+        `spring.application.name=${domain}-service`,
+        `spring.threads.virtual.enabled=true`,
+        `management.endpoints.web.exposure.include=health,info,prometheus`,
+        `spring.jpa.hibernate.ddl-auto=validate`,
+        `spring.datasource.hikari.maximum-pool-size=10`,
+        `server.shutdown=graceful`
+      ].join('\n'),
+      sampleRecordDto: [
+        `package ${pkg}.dto;`,
+        '',
+        `import jakarta.validation.constraints.*;`,
+        '',
+        `public record Create${spec.name || 'Item'}Request(`,
+        `    @NotBlank(message = "Nome é obrigatório") String nome,`,
+        `    @Positive(message = "Valor deve ser positivo") Double valor`,
+        `) {}`
+      ].join('\n'),
+      tier: 1
+    };
+
+    this.setCached('spring_blueprint', queryKey, blueprint, 'spring_blueprint_builder');
+    return blueprint;
+  }
+
+  // ==========================================
+  // SERVIÇO 4: Ciclo de Vida e Suporte LTS de Runtimes
+  // ==========================================
+
+  async getRuntimeLts(techName) {
+    if (!techName) return null;
+    const norm = String(techName).toLowerCase().replace(/[^a-z0-9_]/g, '');
+    let category = 'java';
+    if (norm.includes('node') || norm.includes('js') || norm.includes('typescript')) category = 'nodejs';
+    else if (norm.includes('go') || norm.includes('golang')) category = 'golang';
+    else if (norm.includes('python') || norm.includes('py')) category = 'python';
+    else if (norm.includes('spring')) category = 'spring_boot';
+
+    const cached = this.getCached('runtime_lts', category);
+    if (cached.found && !cached.isExpired) {
+      return { ...cached.data, tier: 2 };
+    }
+
+    // Fallback padrão Tier 3
+    const localData = OFFLINE_RUNTIME_LTS[category] || OFFLINE_RUNTIME_LTS.java;
+    this.setCached('runtime_lts', category, localData, 'offline_runtime_lts', 7 * 24 * 60 * 60 * 1000);
+    return { ...localData, tier: 3 };
+  }
+
+  // ==========================================
+  // SERVIÇO 5: Lookup de Documentação Oficial
+  // ==========================================
+
+  lookupDoc(tech, topic = 'general') {
+    const qTech = String(tech || '').toLowerCase();
+    const qTopic = String(topic || '').toLowerCase();
+
+    const docMap = {
+      java: {
+        officialPortal: 'https://docs.oracle.com/en/java/javase/21/',
+        springGuide: 'https://spring.io/guides',
+        virtualThreads: 'https://openjdk.org/jeps/444',
+        bestPractice: 'Utilize Java 21 Records para entidades imutáveis e DTOs, e ative Virtual Threads via spring.threads.virtual.enabled=true.'
+      },
+      node: {
+        officialPortal: 'https://nodejs.org/docs/latest-v22.x/api/',
+        testRunner: 'https://nodejs.org/api/test.html',
+        sqlite: 'https://nodejs.org/api/sqlite.html',
+        bestPractice: 'Adote o test runner nativo (node:test) e módulos nativos de SQLite (node:sqlite) para dispensar dependências externas voláteis.'
+      },
+      go: {
+        officialPortal: 'https://go.dev/doc/',
+        standardLibrary: 'https://pkg.go.dev/std',
+        concurrency: 'https://go.dev/doc/effective_go#concurrency',
+        bestPractice: 'Prefira goroutines leves e canais com tratamento estrito de context.Context e timeouts para I/O.'
+      },
+      a11y: {
+        officialPortal: 'https://www.w3.org/WAI/WCAG21/quickref/',
+        ariaPatterns: 'https://www.w3.org/WAI/ARIA/apg/patterns/',
+        bestPractice: 'Garanta navegação completa por teclado, atributos alt em imagens, contraste mínimo de 4.5:1 e rótulos acessíveis em botões interativos.'
+      }
+    };
+
+    let selected = docMap.java;
+    if (qTech.includes('node') || qTech.includes('js') || qTech.includes('ts')) selected = docMap.node;
+    else if (qTech.includes('go')) selected = docMap.go;
+    else if (qTech.includes('a11y') || qTech.includes('wcag') || qTopic.includes('a11y')) selected = docMap.a11y;
+
+    return {
+      tech: qTech,
+      topic: qTopic,
+      authoritativeSource: selected.officialPortal,
+      recommendedPractices: selected.bestPractice,
+      links: selected
+    };
+  }
+
+  // ==========================================
+  // GESTÃO DE ESTADO E LIMPEZA
+  // ==========================================
+
+  getCacheStats() {
+    let totalEntries = 0;
+    const byCategory = {};
+
+    if (this.db) {
+      try {
+        const rows = this.db.prepare('SELECT category, COUNT(*) as count FROM knowledge_cache GROUP BY category').all();
+        for (const row of rows) {
+          byCategory[row.category] = row.count;
+          totalEntries += row.count;
+        }
+      } catch (err) {
+        void err;
+      }
+    } else {
+      totalEntries = this.memoryCache.size;
+    }
+
+    return {
+      totalEntries,
+      byCategory,
+      circuitStates: {
+        osv: this.circuits.osv.getStatus(),
+        spring: this.circuits.spring.getStatus(),
+        eol: this.circuits.eol.getStatus()
+      }
+    };
+  }
+
+  clearCache() {
+    if (this.db) {
+      try {
+        this.db.exec('DELETE FROM knowledge_cache');
+      } catch (err) {
+        void err;
+      }
+    }
+    this.memoryCache.clear();
+    return { success: true, message: 'Cache local de conhecimento expurgado com sucesso.' };
+  }
+
+  close() {
+    if (this.db) {
+      try {
+        this.db.close();
+      } catch (err) {
+        void err;
+      }
+      this.db = null;
+    }
+  }
+}
+
+let defaultGatewayInstance = null;
+
+function getKnowledgeGateway(options = {}) {
+  if (!defaultGatewayInstance) {
+    defaultGatewayInstance = new KnowledgeGateway(options);
+  }
+  return defaultGatewayInstance;
+}
+
+module.exports = {
+  KnowledgeGateway,
+  getKnowledgeGateway,
+  inspectEgress,
+  OFFLINE_CVE_CATALOG,
+  OFFLINE_WCAG_RULES,
+  OFFLINE_RUNTIME_LTS
+};