API & Function Reference

Inicializa a conexão PDO com o banco de dados configurado (safend). Usa caching estático interno para evitar múltiplas conexões. Retorna false em caso de erro.

Características: Conexão persistente, tratamento de exceções, timeout de 5 segundos, charset UTF-8MB4, prepared statements desabilitados por padrão.

$db = getSafeNodeDatabase();
if (!$db) {
    die("Erro ao conectar ao banco de dados");
}

$stmt = $db->prepare("SELECT * FROM traffic_logs WHERE ip_address = ?");
$stmt->execute([$_SERVER['REMOTE_ADDR']]);
$logs = $stmt->fetchAll();

Verifica se o banco de dados safend existe e está acessível.

if (!safenodeDatabaseExists()) {
    error_log("Banco de dados safend não encontrado");
    // Criar banco ou exibir erro
}

Retorna a URL base do SafeNode detectada automaticamente do ambiente (HTTP_HOST, SERVER_NAME).

$baseUrl = getSafeNodeBaseUrl();
// Retorna: https://safenode.cloud ou http://localhost/safenode

Aplica todos os headers HTTP de segurança necessários: XSS Protection, Content-Type Options, Frame Options, CSP, HSTS (apenas HTTPS), Referrer Policy, Permissions Policy e Cache Control.

// No início do arquivo PHP
require_once 'includes/HVSecurityHeaders.php';
HVSecurityHeaders::apply();

// Headers aplicados automaticamente:
// - X-XSS-Protection: 1; mode=block
// - X-Content-Type-Options: nosniff
// - X-Frame-Options: DENY
// - Content-Security-Policy: ...
// - Strict-Transport-Security: ... (apenas HTTPS)
// - Referrer-Policy: strict-origin-when-cross-origin
// - Permissions-Policy: geolocation=(), microphone=(), camera=()
// - Cache-Control: no-store, no-cache, must-revalidate

Sanitiza e valida input JSON ou arrays recursivamente. Remove caracteres de controle, limita tamanho de strings (10KB) e sanitiza chaves.

$rawInput = json_decode(file_get_contents('php://input'), true);
$clean = HVSecurityHeaders::sanitizeInput($rawInput);

// Remove caracteres de controle e limita tamanho
// Sanitiza chaves para permitir apenas alfanuméricos, underscore e hífen

Valida o tamanho do payload HTTP. Retorna false e envia HTTP 413 se exceder o limite (padrão: 10KB).

if (!HVSecurityHeaders::validatePayloadSize(5120)) {
    // Payload maior que 5KB - requisição rejeitada
    exit;
}

Valida formato de API key. Deve começar com sk_ e ter pelo menos 35 caracteres (hexadecimal após o prefixo).

$apiKey = $_POST['api_key'] ?? '';
if (!HVSecurityHeaders::validateApiKeyFormat($apiKey)) {
    http_response_code(400);
    echo json_encode(['error' => 'Formato de API key inválido']);
    exit;
}

Valida formato de token. Deve ser hexadecimal de exatamente 64 caracteres.

Registra ameaça detectada na tabela safenode_security_logs com todos os detalhes da requisição.

HVSecurityHeaders::logSecurityThreat(
    $_SERVER['REMOTE_ADDR'],
    'sql_injection',
    $maliciousInput,
    $_SERVER['HTTP_USER_AGENT'],
    $_SERVER['HTTP_REFERER'],
    $siteId
);

Analisa strings em busca de padrões de ataque: SQL Injection, XSS, Command Injection. Retorna o tipo da ameaça ('sql_injection', 'xss', 'command_injection') ou null se seguro.

Padrões detectados: UNION SELECT, INSERT INTO, DELETE FROM, DROP TABLE, OR 1=1, AND 1=1, comentários SQL (--, #, /* */), tags script, javascript:, eventos onerror/onload/onclick, iframes, eval(), base64_decode, comandos shell (ping, nslookup, whoami, etc).

$userInput = $_POST['search'] ?? '';

$threat = HVSecurityHeaders::detectAttack($userInput);
if ($threat) {
    http_response_code(403);
    echo json_encode([
        'error' => 'Ataque detectado: ' . $threat
    ]);
    exit;
}

// Input seguro, processar normalmente
processSearch($userInput);

Implementa rate limiting distribuído baseado em IP usando banco de dados (com fallback para arquivo temporário). Retorna false se o limite foi excedido.

Funcionamento: Usa tabela safenode_hv_rate_limits para rastrear requisições por IP em janelas de tempo. Limpa automaticamente registros antigos. Se o banco não estiver disponível, usa arquivo temporário como fallback.

// Limitar a 30 requisições por minuto
$ip = $_SERVER['REMOTE_ADDR'];
if (!HVSecurityHeaders::checkIpRateLimit($ip, 30, 60)) {
    http_response_code(429);
    header('Retry-After: 60');
    echo json_encode([
        'error' => 'Rate limit excedido. Tente novamente em 60 segundos.'
    ]);
    exit;
}

// Requisição permitida, continuar processamento

Gera um novo token CSRF criptograficamente seguro (64 caracteres hex) e armazena na sessão com timestamp.

Obtém o token CSRF atual da sessão, ou gera um novo se não existir.

Valida o token CSRF usando comparação segura (hash_equals). Tokens expiram após 2 horas.

// No formulário
$token = CSRFProtection::getToken();
echo '';

// Na validação do POST
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $token = $_POST['csrf_token'] ?? '';
    if (!CSRFProtection::validateToken($token)) {
        http_response_code(403);
        die('Token CSRF inválido ou expirado');
    }
    // Processar formulário
}

Retorna HTML do campo hidden com o token CSRF já formatado e escapado.

echo '
';
echo CSRFProtection::getTokenField();
echo '';
echo '
';

Valida automaticamente o token de POST ou GET. Retorna false e envia HTTP 403 se inválido.

Escapa string para uso em HTML (htmlspecialchars com ENT_QUOTES e UTF-8).

$userInput = $_GET['name'] ?? '';
echo '
' . XSSProtection::escape($userInput) . '
';

Escapa string para uso em atributos HTML.

Escapa string para uso em JavaScript (JSON encode).

Sanitiza string removendo tags HTML e caracteres perigosos.

Sanitiza array recursivamente aplicando sanitização em todos os valores string.

Valida formato de email usando filter_var com FILTER_VALIDATE_EMAIL.

Valida formato de URL.

Valida formato de domínio.

Valida string com tamanho mínimo e máximo.

Valida se o valor é um inteiro.

Obtém a subscription ativa do usuário. Se não existir, cria automaticamente um free trial de 14 dias com 10.000 eventos.

$manager = new SubscriptionManager(getSafeNodeDatabase());
$subscription = $manager->getUserSubscription($userId);

if ($subscription) {
    echo "Plano: " . $subscription['plan_type'];
    echo "Eventos usados: " . $subscription['events_used'] . "/" . $subscription['events_limit'];
}

Verifica se o usuário pode usar um evento (tem cota disponível). Retorna false se a cota foi excedida ou a subscription está inativa.

$manager = new SubscriptionManager(getSafeNodeDatabase());

if (!$manager->canUseEvent($userId)) {
    http_response_code(402);
    echo json_encode(['error' => 'Cota de eventos excedida']);
    exit;
}

// Processar evento
processEvent();
$manager->incrementEvent($userId);

Incrementa o contador de eventos usados do usuário.

Retorna estatísticas de uso: eventos usados, limite, porcentagem, data de reset do ciclo.

Cria free trial de 14 dias com 10.000 eventos para o usuário.

Gera código de autorização OAuth criptograficamente seguro (32 caracteres hex). Expira em 10 minutos. Verifica rate limiting antes de gerar.

$manager = new OAuthManager(getSafeNodeDatabase());
$code = $manager->generateAuthorizationCode(
    $userId,
    $appId,
    'https://app.com/callback',
    ['read', 'write'],
    $state
);

// Redirecionar para redirect_uri?code=$code&state=$state
header("Location: $redirectUri?code=$code&state=$state");

Troca código de autorização por access token JWT. Valida credenciais do cliente, código não usado, expiração e redirect URI.

$tokenData = $manager->exchangeCodeForToken(
    $_GET['code'],
    $_POST['client_id'],
    $_POST['client_secret'],
    $_POST['redirect_uri']
);

if ($tokenData) {
    echo json_encode([
        'access_token' => $tokenData['access_token'],
        'token_type' => 'Bearer',
        'expires_in' => 3600,
        'scope' => $tokenData['scope']
    ]);
}

Valida e decodifica token JWT. Retorna dados do usuário e escopos se válido.

Retorna informações do usuário baseado no token e escopos solicitados.

Gera nova API key para Human Verification. Retorna array com api_key (sk_...), api_secret, e configurações.

$keyData = HVAPIKeyManager::generateKey(
    $userId,
    'Meu App',
    'https://meusite.com',
    60, // 60 requisições/minuto
    3600, // Token expira em 1 hora
    'javascript'
);

// $keyData['api_key'] = 'sk_abc123...'
// $keyData['api_secret'] = 'def456...'

Valida API key e verifica se o domínio de origem está permitido. Retorna dados da key se válida.

Verifica rate limit para API key e IP. Retorna array com allowed (bool) e remaining.

Retorna estatísticas completas: uso, performance, geolocalização para o período especificado (24h, 7d, 30d).

Gera código de integração para JavaScript, React, Vue, Node.js, PHP ou Python.

Inicia monitoramento de performance. Registra tempo inicial, memória e endpoint.

Finaliza monitoramento e retorna métricas: tempo de resposta, uso de memória, endpoint. Salva no banco se siteId configurado.

$monitor = new PerformanceMonitor(getSafeNodeDatabase(), $siteId);
$monitor->start('/api/endpoint', 'POST');

// Processar requisição
processRequest();

$metrics = $monitor->end();
// $metrics['response_time'] = 0.234
// $metrics['memory_usage'] = 1024000
// $metrics['endpoint'] = '/api/endpoint'

Executa callback e mede tempo de execução da operação específica.

Cria alerta no sistema. Verifica preferências do usuário antes de enviar notificações. Tipos: attack_detected, rate_limit_exceeded, system_error, etc.

$alertManager = new AlertManager(getSafeNodeDatabase());
$alertId = $alertManager->createAlert(
    $siteId,
    'attack_detected',
    'high',
    'SQL Injection Detectado',
    'Tentativa de SQL injection detectada do IP ' . $_SERVER['REMOTE_ADDR'],
    ['ip' => $_SERVER['REMOTE_ADDR'], 'attack_type' => 'sql_injection']
);

Retorna contagem de alertas não lidos para o site/usuário.

Middleware completo de proteção. Identifica site, verifica status, aplica firewall, geo-blocking, rate limiting e human verification quando necessário.

Funcionalidades: Identificação automática de site, verificação de status ativo, detecção de país por IP, bloqueio geográfico, regras de firewall, rate limiting, desafio humano quando necessário, logging de ameaças.

// No início do arquivo PHP que precisa de proteção
require_once 'includes/SafeNodeMiddleware.php';

// Aplica todas as proteções automaticamente
SafeNodeMiddleware::protect();

// Se passar por todas as verificações, continua execução normal
// Se bloqueado, envia resposta HTTP apropriada e termina execução

Inclui automaticamente todos os assets do tema (CSS, JS, fonts) necessários para o funcionamento da interface.

require_once 'includes/theme-helper.php';
includeThemeAssets();

Renderiza botão de alternância entre tema claro/escuro com funcionalidade JavaScript integrada.