@fabioforest/openclaw 3.0.0

package/lib/ops/audit.js

@@ -0,0 +1,156 @@
+"use strict";
+
+/**
+ * Script operacional: Audit Logging
+ *
+ * Auditoria estruturada (JSON) para todos os eventos do OpenClaw.
+ * Inclui request_id, redaction de segredos e rotação de logs.
+ *
+ * Referência: skills/openclaw-ops/06-openclaw-audit-logging/SKILL.md
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { mask } = require("../security");
+
+// Campos que devem ter seus valores mascarados no log
+const SENSITIVE_FIELDS = ["token", "password", "secret", "privateKey", "apiKey", "auth_token"];
+
+/**
+ * Mascara campos sensíveis recursivamente em um objeto.
+ * @param {object} obj — objeto a ser processado
+ * @returns {object} cópia com valores sensíveis mascarados
+ */
+function redactSensitive(obj) {
+    if (!obj || typeof obj !== "object") return obj;
+
+    const redacted = Array.isArray(obj) ? [...obj] : { ...obj };
+
+    for (const [key, value] of Object.entries(redacted)) {
+        if (typeof value === "object" && value !== null) {
+            redacted[key] = redactSensitive(value);
+        } else if (typeof value === "string" && SENSITIVE_FIELDS.includes(key)) {
+            redacted[key] = mask(value);
+        }
+    }
+
+    return redacted;
+}
+
+/**
+ * Cria uma entrada de log de auditoria.
+ * @param {object} params
+ * @param {string} params.event — tipo do evento (ex: "exec.started")
+ * @param {string} params.requestId — ID da requisição
+ * @param {string} [params.operator] — quem iniciou a ação
+ * @param {string} [params.hostId] — host onde ocorreu
+ * @param {object} [params.details] — detalhes adicionais
+ * @returns {object} entrada de auditoria formatada
+ */
+function createAuditEntry({ event, requestId, operator, hostId, details = {} }) {
+    return {
+        timestamp: new Date().toISOString(),
+        event,
+        requestId,
+        operator: operator || "system",
+        hostId: hostId || "local",
+        details: redactSensitive(details),
+    };
+}
+
+/**
+ * Escreve uma entrada de auditoria no arquivo de log.
+ * @param {string} logDir — diretório de logs
+ * @param {object} entry — entrada de auditoria
+ */
+function writeAuditLog(logDir, entry) {
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    // Arquivo de log diário
+    const date = new Date().toISOString().split("T")[0];
+    const logFile = path.join(logDir, `audit-${date}.jsonl`);
+
+    // Append em formato JSONL (uma linha JSON por entrada)
+    fs.appendFileSync(logFile, JSON.stringify(entry) + "\n", "utf8");
+}
+
+/**
+ * Lê entradas de auditoria de um período.
+ * @param {string} logDir — diretório de logs
+ * @param {object} [filter] — filtros opcionais
+ * @param {string} [filter.date] — data específica (YYYY-MM-DD)
+ * @param {string} [filter.event] — filtrar por tipo de evento
+ * @param {string} [filter.requestId] — filtrar por request_id
+ * @param {number} [filter.limit=100] — limite de entradas
+ * @returns {object[]} entradas de auditoria
+ */
+function readAuditLogs(logDir, filter = {}) {
+    if (!fs.existsSync(logDir)) return [];
+
+    const date = filter.date || new Date().toISOString().split("T")[0];
+    const logFile = path.join(logDir, `audit-${date}.jsonl`);
+
+    if (!fs.existsSync(logFile)) return [];
+
+    const lines = fs.readFileSync(logFile, "utf8")
+        .split("\n")
+        .filter((line) => line.trim());
+
+    let entries = lines.map((line) => {
+        try {
+            return JSON.parse(line);
+        } catch {
+            return null;
+        }
+    }).filter(Boolean);
+
+    // Aplicar filtros
+    if (filter.event) {
+        entries = entries.filter((e) => e.event === filter.event);
+    }
+    if (filter.requestId) {
+        entries = entries.filter((e) => e.requestId === filter.requestId);
+    }
+
+    // Limite
+    const limit = filter.limit || 100;
+    return entries.slice(-limit);
+}
+
+/**
+ * Rotaciona logs mais antigos que o período de retenção.
+ * @param {string} logDir — diretório de logs
+ * @param {number} [retentionDays=30] — dias de retenção
+ * @returns {number} quantidade de arquivos removidos
+ */
+function rotateLogs(logDir, retentionDays = 30) {
+    if (!fs.existsSync(logDir)) return 0;
+
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    let removed = 0;
+
+    const files = fs.readdirSync(logDir).filter((f) => f.startsWith("audit-") && f.endsWith(".jsonl"));
+
+    for (const file of files) {
+        const filePath = path.join(logDir, file);
+        const stats = fs.statSync(filePath);
+
+        if (stats.mtimeMs < cutoff) {
+            fs.unlinkSync(filePath);
+            removed++;
+        }
+    }
+
+    return removed;
+}
+
+module.exports = {
+    redactSensitive,
+    createAuditEntry,
+    writeAuditLog,
+    readAuditLogs,
+    rotateLogs,
+    SENSITIVE_FIELDS,
+};

package/lib/ops/enroll.js

@@ -0,0 +1,133 @@
+"use strict";
+
+/**
+ * Script operacional: Enroll Host
+ *
+ * Onboarding seguro de host na malha WireGuard + OpenClaw
+ * com aprovação humana, identidade e revogação rápida.
+ *
+ * Referência: skills/openclaw-ops/02-openclaw-enroll-host/SKILL.md
+ */
+
+const crypto = require("crypto");
+const os = require("os");
+const path = require("path");
+const { readJsonSafe, writeJsonSafe } = require("../config");
+
+/**
+ * Gera um identificador único para o host.
+ * @returns {{ hostId: string, fingerprint: string, hostname: string }}
+ */
+function generateHostIdentity() {
+    const hostId = crypto.randomUUID();
+    const hostname = os.hostname();
+
+    // Fingerprint baseado em hostname + timestamp + random
+    const raw = `${hostname}-${Date.now()}-${crypto.randomBytes(8).toString("hex")}`;
+    const fingerprint = crypto.createHash("sha256").update(raw).digest("hex").slice(0, 16);
+
+    return { hostId, fingerprint, hostname };
+}
+
+/**
+ * Registra um host no registro de hosts pendentes.
+ * @param {string} registryPath — caminho do arquivo de registro
+ * @param {object} hostInfo — informações do host (hostId, fingerprint, hostname)
+ * @returns {{ success: boolean, host: object }}
+ */
+function registerHost(registryPath, hostInfo) {
+    const registry = readJsonSafe(registryPath) || { hosts: [] };
+
+    const entry = {
+        ...hostInfo,
+        status: "pending",
+        registeredAt: new Date().toISOString(),
+        approvedAt: null,
+        approvedBy: null,
+    };
+
+    registry.hosts.push(entry);
+    writeJsonSafe(registryPath, registry);
+
+    return { success: true, host: entry };
+}
+
+/**
+ * Aprova um host pendente.
+ * @param {string} registryPath — caminho do arquivo de registro
+ * @param {string} hostId — ID do host a aprovar
+ * @param {string} approvedBy — quem aprovou
+ * @returns {{ success: boolean, host?: object, error?: string }}
+ */
+function approveHost(registryPath, hostId, approvedBy) {
+    const registry = readJsonSafe(registryPath);
+    if (!registry || !registry.hosts) {
+        return { success: false, error: "Registro de hosts não encontrado" };
+    }
+
+    const host = registry.hosts.find((h) => h.hostId === hostId);
+    if (!host) {
+        return { success: false, error: `Host ${hostId} não encontrado` };
+    }
+
+    if (host.status === "approved") {
+        return { success: false, error: `Host ${hostId} já está aprovado` };
+    }
+
+    host.status = "approved";
+    host.approvedAt = new Date().toISOString();
+    host.approvedBy = approvedBy;
+
+    writeJsonSafe(registryPath, registry);
+    return { success: true, host };
+}
+
+/**
+ * Revoga um host (remove acesso).
+ * @param {string} registryPath — caminho do arquivo de registro
+ * @param {string} hostId — ID do host a revogar
+ * @param {string} revokedBy — quem revogou
+ * @returns {{ success: boolean, host?: object, error?: string }}
+ */
+function revokeHost(registryPath, hostId, revokedBy) {
+    const registry = readJsonSafe(registryPath);
+    if (!registry || !registry.hosts) {
+        return { success: false, error: "Registro de hosts não encontrado" };
+    }
+
+    const host = registry.hosts.find((h) => h.hostId === hostId);
+    if (!host) {
+        return { success: false, error: `Host ${hostId} não encontrado` };
+    }
+
+    host.status = "revoked";
+    host.revokedAt = new Date().toISOString();
+    host.revokedBy = revokedBy;
+
+    writeJsonSafe(registryPath, registry);
+    return { success: true, host };
+}
+
+/**
+ * Lista hosts filtrados por status.
+ * @param {string} registryPath — caminho do arquivo de registro
+ * @param {string} [statusFilter] — filtrar por status (pending, approved, revoked)
+ * @returns {object[]} lista de hosts
+ */
+function listHosts(registryPath, statusFilter) {
+    const registry = readJsonSafe(registryPath);
+    if (!registry || !registry.hosts) return [];
+
+    if (statusFilter) {
+        return registry.hosts.filter((h) => h.status === statusFilter);
+    }
+    return registry.hosts;
+}
+
+module.exports = {
+    generateHostIdentity,
+    registerHost,
+    approveHost,
+    revokeHost,
+    listHosts,
+};

package/lib/ops/exec.js

@@ -0,0 +1,140 @@
+"use strict";
+
+/**
+ * Script operacional: Remote Exec (Runbooks)
+ *
+ * Estrutura execução remota via VPN usando runbooks nomeados,
+ * idempotentes, com timeout, cancel e trilha auditável.
+ *
+ * Referência: skills/openclaw-ops/04-openclaw-remote-exec-runbooks/SKILL.md
+ */
+
+const { execSync, spawn } = require("child_process");
+const crypto = require("crypto");
+
+/**
+ * Gera um request_id único para rastrear a execução.
+ * @returns {string} request_id no formato "req-<uuid>"
+ */
+function generateRequestId() {
+    return `req-${crypto.randomUUID()}`;
+}
+
+/**
+ * Valida as entradas de um runbook antes da execução.
+ * @param {object} runbook — definição do runbook
+ * @param {string} runbook.name — nome do runbook
+ * @param {string} runbook.command — comando a executar
+ * @param {string[]} [runbook.allowedArgs] — args permitidos
+ * @param {object} [inputs] — inputs do usuário
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateInputs(runbook, inputs = {}) {
+    const errors = [];
+
+    if (!runbook.name) errors.push("Nome do runbook é obrigatório");
+    if (!runbook.command) errors.push("Comando do runbook é obrigatório");
+
+    // Validar que inputs não contêm injection
+    for (const [key, value] of Object.entries(inputs)) {
+        if (typeof value === "string" && /[;&|`$()]/.test(value)) {
+            errors.push(`Input '${key}' contém caracteres proibidos: ${value}`);
+        }
+    }
+
+    return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Executa um runbook de forma segura com timeout e captura de saída.
+ * @param {object} params
+ * @param {string} params.command — comando a executar
+ * @param {number} [params.timeoutMs=30000] — timeout em ms
+ * @param {string} [params.cwd] — diretório de trabalho
+ * @returns {{ requestId: string, exitCode: number, stdout: string, stderr: string, timedOut: boolean, duration: number }}
+ */
+function executeRunbook({ command, timeoutMs = 30000, cwd }) {
+    const requestId = generateRequestId();
+    const startTime = Date.now();
+
+    try {
+        const stdout = execSync(command, {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            cwd: cwd || undefined,
+            maxBuffer: 1024 * 1024, // 1MB
+        });
+
+        return {
+            requestId,
+            exitCode: 0,
+            stdout: stdout.trim(),
+            stderr: "",
+            timedOut: false,
+            duration: Date.now() - startTime,
+        };
+    } catch (err) {
+        return {
+            requestId,
+            exitCode: err.status || 1,
+            stdout: (err.stdout || "").trim(),
+            stderr: (err.stderr || err.message || "").trim(),
+            timedOut: err.killed || false,
+            duration: Date.now() - startTime,
+        };
+    }
+}
+
+/**
+ * Executa um runbook em background com possibilidade de cancelamento.
+ * @param {object} params
+ * @param {string} params.command — comando a executar
+ * @param {number} [params.timeoutMs=30000] — timeout em ms
+ * @returns {{ requestId: string, process: object, cancel: function }}
+ */
+function executeAsync({ command, timeoutMs = 30000 }) {
+    const requestId = generateRequestId();
+    const parts = command.split(" ");
+    const child = spawn(parts[0], parts.slice(1), {
+        timeout: timeoutMs,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    const cancel = () => {
+        if (!child.killed) {
+            child.kill("SIGTERM");
+            // Force kill após 5s se não responder
+            setTimeout(() => {
+                if (!child.killed) child.kill("SIGKILL");
+            }, 5000);
+        }
+    };
+
+    return { requestId, process: child, cancel };
+}
+
+/**
+ * Formata o resultado de uma execução para log.
+ * @param {object} result — resultado da execução
+ * @returns {object} objeto formatado para auditoria
+ */
+function formatForAudit(result) {
+    return {
+        requestId: result.requestId,
+        exitCode: result.exitCode,
+        timedOut: result.timedOut,
+        duration: `${result.duration}ms`,
+        timestamp: new Date().toISOString(),
+        // Trunca saída para auditoria (max 500 chars)
+        stdoutPreview: result.stdout.slice(0, 500),
+        stderrPreview: result.stderr.slice(0, 500),
+    };
+}
+
+module.exports = {
+    generateRequestId,
+    validateInputs,
+    executeRunbook,
+    executeAsync,
+    formatForAudit,
+};

package/lib/ops/healthcheck.js

@@ -0,0 +1,167 @@
+"use strict";
+
+/**
+ * Script operacional: Healthchecks
+ *
+ * Heartbeat via VPN, alertas e autocura com limites.
+ * Circuit breaker para bloquear exec quando instável.
+ *
+ * Referência: skills/openclaw-ops/08-openclaw-healthchecks/SKILL.md
+ */
+
+const { portInUse } = require("../security");
+
+/**
+ * Estado do circuit breaker.
+ * @typedef {'closed'|'open'|'half-open'} CircuitState
+ */
+
+/**
+ * Cria uma instância de circuit breaker.
+ * @param {object} [options]
+ * @param {number} [options.failureThreshold=2] — falhas consecutivas para abrir
+ * @param {number} [options.resetTimeoutMs=60000] — tempo para tentar half-open (ms)
+ * @returns {object} circuit breaker com métodos record, canExecute, getState, reset
+ */
+function createCircuitBreaker({ failureThreshold = 2, resetTimeoutMs = 60000 } = {}) {
+    let state = "closed";
+    let failures = 0;
+    let lastFailureTime = null;
+
+    return {
+        /**
+         * Registra resultado de uma operação.
+         * @param {boolean} success — se a operação teve sucesso
+         * @returns {CircuitState} estado atual após o registro
+         */
+        record(success) {
+            if (success) {
+                failures = 0;
+                state = "closed";
+                return state;
+            }
+
+            failures++;
+            lastFailureTime = Date.now();
+
+            if (failures >= failureThreshold) {
+                state = "open";
+            }
+
+            return state;
+        },
+
+        /**
+         * Verifica se é seguro executar uma operação.
+         * @returns {{ allowed: boolean, state: CircuitState, reason?: string }}
+         */
+        canExecute() {
+            if (state === "closed") {
+                return { allowed: true, state };
+            }
+
+            if (state === "open") {
+                // Verificar se já passou o timeout para half-open
+                const elapsed = Date.now() - (lastFailureTime || 0);
+                if (elapsed >= resetTimeoutMs) {
+                    state = "half-open";
+                    return { allowed: true, state, reason: "Testando recuperação (half-open)" };
+                }
+                return {
+                    allowed: false,
+                    state,
+                    reason: `Circuit breaker aberto — ${failures} falhas consecutivas. Aguardando ${Math.ceil((resetTimeoutMs - elapsed) / 1000)}s`,
+                };
+            }
+
+            // half-open: permite uma tentativa
+            return { allowed: true, state, reason: "Half-open: tentativa de recuperação" };
+        },
+
+        /** Retorna o estado atual. */
+        getState() {
+            return { state, failures, lastFailureTime };
+        },
+
+        /** Reseta o circuit breaker. */
+        reset() {
+            state = "closed";
+            failures = 0;
+            lastFailureTime = null;
+        },
+    };
+}
+
+/**
+ * Executa um heartbeat verificando a saúde básica do sistema.
+ * @param {object} [options]
+ * @param {number} [options.port=18789] — porta a verificar
+ * @param {string} [options.host=127.0.0.1] — host a verificar
+ * @returns {Promise<{ healthy: boolean, checks: object[] }>}
+ */
+async function heartbeat({ port = 18789, host = "127.0.0.1" } = {}) {
+    const checks = [];
+
+    // Check 1: Porta do serviço
+    try {
+        const inUse = await portInUse(port, host);
+        checks.push({
+            name: `port:${port}`,
+            status: inUse ? "ok" : "fail",
+            message: inUse ? `Serviço respondendo em ${host}:${port}` : `Porta ${port} livre — serviço pode estar parado`,
+        });
+    } catch (err) {
+        checks.push({
+            name: `port:${port}`,
+            status: "fail",
+            message: `Erro ao verificar porta: ${err.message}`,
+        });
+    }
+
+    const healthy = checks.every((c) => c.status === "ok");
+    return { healthy, checks, timestamp: new Date().toISOString() };
+}
+
+/**
+ * Tenta auto-restart com limites de tentativas.
+ * @param {object} params
+ * @param {function} params.restartFn — função que executa o restart
+ * @param {function} params.healthFn — função que verifica saúde
+ * @param {number} [params.maxRetries=3] — máximo de tentativas
+ * @param {number} [params.delayMs=5000] — delay entre tentativas (ms)
+ * @returns {Promise<{ success: boolean, attempts: number, error?: string }>}
+ */
+async function autoRestart({ restartFn, healthFn, maxRetries = 3, delayMs = 5000 }) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            await restartFn();
+
+            // Aguardar antes de verificar
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+
+            const healthy = await healthFn();
+            if (healthy) {
+                return { success: true, attempts: attempt };
+            }
+        } catch (err) {
+            if (attempt === maxRetries) {
+                return {
+                    success: false,
+                    attempts: attempt,
+                    error: `Falha após ${maxRetries} tentativas: ${err.message}`,
+                };
+            }
+        }
+
+        // Delay incremental entre tentativas
+        await new Promise((resolve) => setTimeout(resolve, delayMs * attempt));
+    }
+
+    return { success: false, attempts: maxRetries, error: "Excedido limite de tentativas" };
+}
+
+module.exports = {
+    createCircuitBreaker,
+    heartbeat,
+    autoRestart,
+};